CLOCKMAKER 2.x (DEBIAN PACKAGE)
-------------------------------


Thanks for trying out ClockMaker! This Debian package is intended for installing ClockMaker onto Debian-based distros. If your distro isn't Debian-based, you'll need to install ClockMaker from the generic archive package instead.


RUNNING CLOCKMAKER

When ClockMaker is run from your system's menu (or it is run from the command line without arguments), it displays the "Default" clock. To change the displayed clock or to alter its properties, you must access the app's menu which is accessible via a right-click. In addition to "About" and "Quit", this menu provides access to the following three options:


Clocks

The "Clocks" menu option displays a dialog that enables you to set which clock is displayed. This dialog can also be used to maintain the list of clocks available. For instance, you can create a new clock from an existing one simply by typing a new name into the clock dropdown and then clicking the "Save" button.

The Clocks dialog also allows you to delete clocks. Simply select the clock you wish to delete and then click the "Delete" button.


Properties

The "Properties" menu option displays the properties dialog. As its name suggests, this dialog enables you to change a clock's properties. In the top section of the dialog, you can set the layers that comprise the clock's face. ClockMaker renders a clock face from up to five different layers: background, border, numeral, tickmark and extra. A given clock can employ any combination of these five layers. Generally, you'll use the background layer to specify just a background image which might be a solid color, a gradient or perhaps an image of something but there's nothing to prevent you from placing other clock "components" on this or any other layer. An example of a clock that uses just one layer for all of its components is the "Default" clock, the background layer of which consists of the numerals and tickmarks in addition to a white background. As you might expect, the border, numeral and tickmark layers provide for rendering borders, numerals and tickmarks but not quite so obvious is the "extra" layer which is typically used to render anything that isn't otherwise accounted for by the other layers and you'll notice that some of the pre-built clocks use this layer to render text or "highlights" onto the clock face. 

In the middle section of the dialog, you can change properties pertaining to the clock hands. For each hand, you can set its fill and stroke (or border) colors as well as its stroke width. Note that stroke widths are specified as a fraction with respect to the clock's radius.

Each hand in ClockMaker is defined as a scalable vector graphic (SVG) and thus the "SVG Defn." column here points to the chosen SVG definition per each hand. For the "Default" clock you'll notice that its hour hand definition is "rect-hr-ofs-1". This identifier corresponds to a file of the same name (with ".svg" appended) that is found in the "hands" subfolder beneath ClockMaker's application folder. Here, "ofs" denotes that the hand is defined having a counterbalance or offset. The "-1" suffix denotes that this is the first hour hand definition having an offset and if you were to create a new hour hand that was perhaps a bit shorter, you could then name it as "rect-hr-ofs-2" (though ClockMaker in no way forces you to adhere to this convention--you could just as easily name the new definition "rect-hr-ofs-short-1" if so desired).

In the final section of the Properties dialog, you can alter the cap size and color. Here, "cap" refers to the small disc or filled circle that appears at the center of the clock on top of the clock hands. Note that the cap's size is specified as a fraction with respect to the clock's radius.

WARNING: Changes made to a clock's properties will not automatically be saved! After changing a clock's properties, if you want the changes to be permanent, you must save the clock with its new properties by opening the Clocks dialog and then clicking the "Save" button!


Help

The "Help" menu option displays the application's readme.txt file (this file).


Running ClockMaker From the Command Line

With the exception of maintaining the list of saved clocks, everything that can be done via ClockMaker's GUI can also be done from the command line. You can set which clock is displayed and you can alter its properties. In addition, you can specify the size of the displayed clock. If you wish to save a clock that has been designed at the command line, you can do this once the clock is displayed by using the instructions above for saving a clock from the GUI.

For complete details on running ClockMaker from the command line, you can either view ClockMaker's man page by running "man clockmaker" or you can run the app with the "--help" option.


Making Your Own Clock Component Images

ClockMaker comes packaged with a modest set of clock component images for the background, border, numeral, tickmark and extra layers. Adding to these existing component images is a matter of either creating your own images in a graphics editor like GIMP or finding suitable images on the web. All such images should have a square aspect ratio (width = height) and although technically, they can be of any reasonable dimension or size, a size of 1000 pixels is generally ideal (assuming that your displayed clocks won't be significantly larger than this value).

Note that just because a component image must be of a square aspect, this doesn't mean that the visible part of the image must likewise be "square". That part of the clock face which is actually visible can take almost any shape you can imagine, so long as it fits within the square aspect image.

Note also that the size of clock component images has no real bearing on the size of the displayed clock as such images are automatically scaled to match the display size of the clock. That said, if you intend to display your clocks at say, 1000 pixels and the numerals image is only 200 pixels then be aware that the numerals may turn out to be pixelated. One last thing worth mentioning is that, in order to work with ClockMaker, all component images must be of type .png as an alpha channel is needed in order to achieve transparency (for example, transparent corners).

To create a background image's transparent corners using GIMP, you can apply a mask to the image based on an elipse (circular) selection. First be sure that the image layer has an alpha channel and then choose the elipse selection tool, select the entire image (using ctrl-A) and finally, add (and apply) a mask to the image layer based on this selection. If done right, this will result in your image having transparent corners.

Now, having explained how this is essentially done from scratch, realize that you can always just copy an existing component image to serve as the basis for a new one...


Making Your Own Clock Hands

Although comprehensive instructions for creating custom clock hands is beyond the scope of this document, following are a few pointers that can help you get started. I highly recommend using the free online app, "SVG Path Editor" (https://yqnn.github.io/svg-path-editor/) to design your clock hands. You'll find documentation for using it on GitHub (https://github.com/Yqnn/svg-path-editor).

Create the hand shape in the SVG Path Editor as though it is within a "viewbox" that's 200x200 units square, is centered at (0,0) and the hand itself is oriented in the 3 oclock position with its left end at (or near) the origin (0,0). This ought to provide sufficient "resolution" for you to design with.

To modify a hand definition or to create a new definition from an existing one, do the following:

1. Copy the path data from the existing hand definition (.svg) file (beginning with the first "M" command).
2. Paste the copied path data into the "PATH" text widget located in the top, left corner of the SVG Path Editor.
3. Use the "Scale" function with X and Y scale factors of "100" each to expand the design into a 200x200 viewbox workspace.
4. Edit the design to your liking. Note that you can drag line segment endpoints to reposition them as well as insert and delete line segments. 
5. Once you're done with your design, use the "Scale" function with X and Y scale factors of "0.01" each to shrink the design back down to ClockMaker's 2x2 viewbox.
6. Copy the updated path data (again, located in the top, left corner of the SVG Path Editor) and incorporate it into the new hand definition (.svg) file.


CLOCKMAKER ONLINE

For more information regarding ClockMaker visit its web page online: https://valaclock-55dc3f.gitlab.io/.


HOW TO CONTACT THE AUTHOR

If you have any questions or comments regarding ClockMaker, feel free to message me on Reddit (u/pc_load_ltr) or to send me an email (bwblock@protonmail.com).

