CLOCKMAKER 2.x (GENERIC ARCHIVE PACKAGE)
----------------------------------------


Thanks for trying out ClockMaker! This generic, .tar.gz archive is primarily intended for anyone installing ClockMaker on a Linux system for which there is presently no native distribution package available (i.e., a .RPM package). If you're installing ClockMaker onto a Debian-based distro, you may want to consider installing from the Debian package (.deb) instead--though this generic archive should still work.


INSTALLING CLOCKMAKER

NOTE: The script included in this archive will install ClockMaker locally, beneath your home folder (in the ".clockmaker" subfolder) and therefore, the app will only be available to your user and no other users on your system. For other users to run ClockMaker, they will need to install the app following these instructions.

WARNING: If you have a prior version of ClockMaker installed, BE SURE TO UNINSTALL IT FIRST before proceeding with these instructions! If you previously installed ClockMaker from the generic archive package, see the section, "UNINSTALLING CLOCKMAKER". If you previously installed ClockMaker from the Debian package (.deb), you'll need to uninstall it accordingly.

To install ClockMaker from the extracted .tar.gz archive, follow these steps:

1. Open a terminal instance in the extracted folder. This can generally be done from within a file manager by right-clicking inside of the folder itself and then choosing "Open in Terminal", or a similar option.

2. From the terminal, run the "install-clockmaker.sh" bash script as follows:

   ./install-clockmaker.sh
   
This will install ClockMaker onto your computer, outputting each step performed. 

3. Once the installation script is finished you should be able to run ClockMaker from the system menu. If all has gone according to plan, you should see ClockMaker's GUI (the default clock) appear on the desktop. If ClockMaker can't be found in the menu or it fails to run, continue on to the next section.

Note that ClockMaker can be run from the command line; however, this generic package DOES NOT add it to your system's path. If you'd like to run ClockMaker in a terminal from any folder on your system, you'll need to create a symlink pointing to its binary file (located in "~/.clockmaker") and then move this symlink to a folder that's included in your system's PATH environment variable. On a Linux system that conforms to the freedesktop standard you should be able to copy the symlink into the folder, "~/.local/bin". Note that this folder might not already exist and if that's the case you can create it yourself.


IF YOU ENCOUNTER PROBLEMS DURING INSTALL

If ClockMaker fails to run properly, then one or more of its dependencies is likely missing and needs to be installed. See the file, "dependencies.txt" for the list of libraries that ClockMaker is dependent on. To get ClockMaker up and running, you'll need to query your system's package management database in order to determine which of the dependencies is missing and must be installed.

If ClockMaker isn't appearing in the system menu, you may need to log out and back in to your system. If that doesn't work, then it may be that the folder to which the symlink was copied isn't being searched for apps to be added to the menu, in which case you'll need to determine which folder is being searched and then manually move the symlink into it.


UNINSTALLING CLOCKMAKER

Should you decide to uninstall ClockMaker from your system (assuming it was previously installed using this generic script package), all that you need to do is delete its hidden folder (~/.clockmaker) that's created beneath your home folder and then delete the symlink to ClockMaker's launcher file that's placed into ~/.local/share/applications.


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 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).

