<title>Guifications Theme Howto</title>

<releaseinfo>0.1</releaseinfo>

<date>8 May 2005</date>

<firstname>Gary</firstname>

<surname>Kramlich</surname>

<email>grim@reaperworld.com</email>

<revnumber>1.0</revnumber>

<date>8 May 2005</date>

<authorinitials>gk</authorinitials>

<revremark>Initial version</revremark>

<title>Introduction</title>

This guide was written to help new theme authors get a good start

on understanding the capabilities of the theme editor.

Unfortunately it is not very intuitive, but I hope to make it a bit

easier to work with as time goes on.

This guide is not meant to be comprehensive, it's focus is on the

use of the Guifications theme editor and nothing more.

<title>The Theme Editor</title>

<title>The Theme Editor</title>

This is the theme editor, the user interface is pretty clunky, but

it is slowly getting better over time.

Across the top, there is a menu bar where you can add and remove

items and notifications. On the left is the actual tree that makes

up the theme. It starts with the theme itself, which contains

information, options and notifications, while notification contain

items. If that didn't sit well with you, don't worry it will all

become clear throughout the rest of this howto. On the right you

will be doing the majority of your editing. This area is used to

update probably more settings than you'd expect.

<title>Toolbar</title>

<entry>New Theme</entry>

<entry>Creates a new theme.</entry>

<entry>Save Theme</entry>

<entry>Saves the current theme.</entry>

<entry>New Notification</entry>

<entry>Creates a new notification.</entry>

<entry>New Item</entry>

<entry>Creates a new item.</entry>

<entry>Duplicate</entry>

Creates a duplicate of a notification or an item.

<entry>Delete</entry>

<entry>Deletes a notification or an item.</entry>

<entry>Move Up</entry>

Moves a notification or an item up in the list.

While the order of notifications has no impact on

how Guifications treats the theme, it can be handy

to move them around.

Items however, are drawn in the order that they are

in the theme. So, if you wanted to create a layer

effect, or add drop shadows, you can do that by

making sure your shadow is above the actual item

that it is a shadow for.

<entry>Move Down</entry>

Moves a notification or an item down in the list.

<entry>Help</entry>

<entry>Brings you to this tutorial.</entry>

<title>Editing Theme Information</title>

<title>Theme Information Page</title>

This is the theme information page. Here you can set some basic

information about your theme. These fields should be

self-explanatory, so they will not be discused further.

NOTE: Theme names MUST be unique to not only avoid confusion in the

theme list, but they are used to create the directory for new

themes.

<title>Editing Theme Options</title>

<title>Theme Options Page</title>

The time and date formats follow the strftime format. A simple

google search for 'strftime' or a 'man 3 strftime' on Unix should

be able to help you there.

Warning is the text to display if a text item contains a %w and the

protocol for the notification does not support warning levels.

This would be any protocols besides AIM or ICQ.

Ellipsis is the text to use when clipping text. If your clipping

format for text items is set to truncate this option has no effect.

<title>Creating Notifications</title>

<title>New Notification Window</title>

When you click on the new notification button in the toolbar, you

will be presented with this window. It contains a dropdown of all

of the currently available notifications, as well as a master

notification.

A master notification is used as a template for any notifications

created after it. When you create a new theme, a master

notification will automatically be created for you. If you know

your theme is going to look basically the same for all

notifications, you can create a master notification that already

has a background image set, contains some text, and any other

items you want.

You can add as many notifications of as many types as you want.

When an event happens, Guifications looks at all the loaded themes,

checks how notifications of that type that they have, and chooses

one at random to display. This gives another level to

customization, since you do not have to create another theme if you

want to make the same notifications have subtle differences.

<title>Editing Notifications</title>

<title>The Notification Page</title>

In the notification page, you will create the basic look of your

notification. You can have it fit in with your gtk theme by

checking the 'Use Gtk theme background' or you can choose to use

an image. Guifications supports 1-bit alpha which you can use to

create non-rectangular notifications.

If you choose to use the Gtk theme's background, you can decide how

big you want the notification. If you decide that you want to use

an image as the background, the notification size will be set to

the size of the image. If the image is non-rectangular, it will

still use the resolution of the image.

The alias entry has been added for those of you that would like to

support multiple notifications of the same type in a theme. By

using aliases, you can tell at a glance which notification is

which. Hopefully this will prove to be useful for someone besides

me. :)

<title>Creating Items</title>

<title>New Item Window</title>

Similar to the new notification window, the new item window

presents you with a list of all the currently available items.

Notifications can contain as many items as many times as they want.

You can use this, with the order they are in to have text overlay

icons and images, or to add drop shadows, or anything else you can

think of.

<title>Editing Icons</title>

<title>Icon Page</title>

All items have three common attributes. These are position,

horizontal offset, and vertical offset. Guifications does not

place items like most people are used to. You select a general

position of where the item will be placed (Top Left, Center,

Bottom Right, etc) and then place it exactly where you want it by

using the horizontal and vertical offsets. As you can see in the

screen shot, the offsets can also be used as percentages. All

items use the notification's height and width to calculate the

values of the percentages.

Icons have two unique attributes. These are type and size. The

type is what type of icon to show, which includes protocol, status,

and buddy icon. Size is the size to scale the icon too. You can

choose from some previously defined values between 16x16 all the

way to 144x144.

<title>Editing Images</title>

<title>Image Page</title>

Images have one unique attribute which is the image to display.

Guifications supports any image format that Gtk supports, which

gives you quite a range to choose from. However, if you are

planning on distrubuting your theme, then you'll probably want to

stick to the formats that Gtk supports internally.

<title>Editing Text</title>

<title>Text Page</title>

Text has five atrributes that you can modify. The first is the

format string to use (See the table below for specifics). Width

allows you to set a maximum width for the text. If the width is

zero or greater than the width of the notification it will

automatically be set to the width of the notification minus the

position of the text. Clipping allows you to decide what happens

when all of the text will not fit. You have four options for when

this occurs. You can either truncate the text, or put an ellipsis

at the beginning, middle, or end. The text that is used for the

ellipsis can be modified within the theme options page. Lastly,

there is font and color, which modify the text's font and color

respectively.

<title>Format Tokens</title>

<entry>%</entry>

<entry>A literal '%'</entry>

<entry>a</entry>

<entry>Account name</entry>

<entry>C</entry>

<entry>The conversation title</entry>

<entry>c</entry>

<entry>The conversation name</entry>

<entry>D</entry>

<entry>Date formatted using the theme option</entry>

<entry>d</entry>

<entry>The day of the month</entry>

<entry>H</entry>

<entry>Hour (0-23)</entry>

<entry>h</entry>

<entry>Hour (0-12)</entry>

<entry>i</entry>

<entry>Your public IP address</entry>

<entry>M</entry>

<entry>Month (1-12)</entry>

<entry>m</entry>

<entry>Minute (0-59)</entry>

<entry>N</entry>

<entry>Computer name</entry>

<entry>n</entry>

<entry>Buddy's name (following preferences for aliases)</entry>

<entry>p</entry>

<entry>Protocol ID</entry>

<entry>r</entry>

<entry>Received message</entry>

<entry>s</entry>

<entry>Seconds (0-59)</entry>

<entry>T</entry>

<entry>Time formatted using the theme option</entry>

<entry>t</entry>

<entry>Seconds since the epoc</entry>

<entry>u</entry>

<entry>Computer username</entry>

<entry>W</entry>

<entry>The name of who warned you (Does this even work?)</entry>

<entry>w</entry>

<entry>Your warning level or the theme option</entry>

<entry>X</entry>

<entry>Extra info (needs clarification)</entry>

<entry>Y</entry>

<entry>Year with century</entry>

<entry>y</entry>

<entry>Year without century</entry>

<title>Deleting Items and Notifications</title>

<title>Delete Window</title>

When you click the delete button in the toolbar when an item or a

notification is selected you will be presented with this dialog.

This is your last chance to keep your item or notification, since

currently there is no undo functionality. If you delete an item or

a notification, there is no way to restore it, except by manually

recreating it.

<title>Saving</title>

Once you have populated your theme with a fair ammount of

notifications and items, hit the save button in the toolbar.

Guifications will notice when this happens and update the theme

list in preferences if you have it open. From the themes list you

can load your theme, and see it in action!

<title>Summary</title>

Guifications has always been about user customization, and with the

introduction of themes in 2.x it has been taken to a new level. I

love seeing people submitting new themes as well. You can always

submit your themes to the

<ulink url="http://sf.net/tracker/?atid=676821&amp;group_id=92888&amp;func=browse">theme tracker</ulink>

on <ulink url="http://sf.net">sourceforge.net</ulink>.

If you have any questions or comments, please don't be afraid to

ask. You can always find us in #guifications on irc.freenode.net,

or by sending an email to

<ulink url="mailto:guifications-devel@lists.guifications.org">guifications-devel@lists.guifications.org</ulink>.

I hope this tutorial has been helpful, and as always, thank you for

using Guifications.