grim/guifications2-theme-howto

Initial import!
start
2005-05-08, amc_grim
27610116ccd6
Parents
Children 29240f49a0c9
Initial import!
14 files changed, 518 insertions(+), 0 deletions(-)
  • +12 -0
    Makefile
  • +1 -0
    Makefile.opts
  • +485 -0
    gf_theme_howto.xml
  • +20 -0
    images/Makefile
  • +0 -0
    images/item_delete.png
  • +0 -0
    images/item_icon_page.png
  • +0 -0
    images/item_image_page.png
  • +0 -0
    images/item_new.png
  • +0 -0
    images/item_text_page.png
  • +0 -0
    images/notification_new.png
  • +0 -0
    images/notification_page.png
  • +0 -0
    images/theme_editor.png
  • +0 -0
    images/theme_info.png
  • +0 -0
    images/theme_ops.png
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/Makefile Sun May 08 08:02:54 2005 +0000
    @@ -0,0 +1,12 @@
    +SOURCE=gf_theme_howto.xml
    +
    +include Makefile.opts
    +
    +all:
    + $(MAKE) -C images
    + docbook2html -o $(OUTPUT) $(SOURCE)
    +
    +clean:
    + $(MAKE) -C images clean
    + rm -rf $(OUTPUT)
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/Makefile.opts Sun May 08 08:02:54 2005 +0000
    @@ -0,0 +1,1 @@
    +OUTPUT=output
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gf_theme_howto.xml Sun May 08 08:02:54 2005 +0000
    @@ -0,0 +1,485 @@
    +<?xml version="1.0"?>
    +<!DOCTYPE article PUBLIC "-//OASIS/DTD DocBook XML V4.1.2//EN"
    + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
    +
    +<article id="index">
    + <articleinfo>
    + <title>Guifications Theme Howto</title>
    + <releaseinfo>0.1</releaseinfo>
    + <date>8 May 2005</date>
    + <authorgroup>
    + <author>
    + <firstname>Gary</firstname>
    + <surname>Kramlich</surname>
    + <affiliation>
    + <address>
    + <email>grim@reaperworld.com</email>
    + </address>
    + </affiliation>
    + </author>
    + </authorgroup>
    + <revhistory>
    + <revision>
    + <revnumber>1.0</revnumber>
    + <date>8 May 2005</date>
    + <authorinitials>gk</authorinitials>
    + <revremark>Initial version</revremark>
    + </revision>
    + </revhistory>
    + </articleinfo>
    +
    + <sect1 id="intro">
    + <title>Introduction</title>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + This guide is not meant to be comprehensive, it's focus is on the
    + use of the Guifications theme editor and nothing more.
    + </para>
    + </sect1>
    +
    + <sect1 id="theme-editor">
    + <title>The Theme Editor</title>
    +
    + <figure>
    + <title>The Theme Editor</title>
    + <graphic fileref="images/theme_editor.png" />
    + </figure>
    +
    + <para>
    + This is the theme editor, the user interface is pretty clunky, but
    + it is slowly getting better over time.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    +
    + <table>
    + <title>Toolbar</title>
    +
    + <tgroup cols="2">
    + <tbody valign="top">
    + <row>
    + <entry>New Theme</entry>
    + <entry>Creates a new theme.</entry>
    + </row>
    + <row>
    + <entry>Save Theme</entry>
    + <entry>Saves the current theme.</entry>
    + </row>
    + <row>
    + <entry>New Notification</entry>
    + <entry>Creates a new notification.</entry>
    + </row>
    + <row>
    + <entry>New Item</entry>
    + <entry>Creates a new item.</entry>
    + </row>
    + <row>
    + <entry>Duplicate</entry>
    + <entry>
    + Creates a duplicate of a notification or an item.
    + </entry>
    + </row>
    + <row>
    + <entry>Delete</entry>
    + <entry>Deletes a notification or an item.</entry>
    + </row>
    + <row>
    + <entry>Move Up</entry>
    + <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>
    + </row>
    + <row>
    + <entry>Move Down</entry>
    + <entry>
    + Moves a notification or an item down in the list.
    + </entry>
    + </row>
    + <row>
    + <entry>Help</entry>
    + <entry>Brings you to this tutorial.</entry>
    + </row>
    + </tbody>
    + </tgroup>
    + </table>
    + </sect1>
    +
    + <sect1 id="page-theme-info">
    + <title>Editing Theme Information</title>
    +
    + <figure>
    + <title>Theme Information Page</title>
    + <graphic fileref="images/theme_info.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="page-theme-options">
    + <title>Editing Theme Options</title>
    +
    + <figure>
    + <title>Theme Options Page</title>
    + <graphic fileref="images/theme_ops.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="window-notification-new">
    + <title>Creating Notifications</title>
    +
    + <figure>
    + <title>New Notification Window</title>
    + <graphic fileref="images/notification_new.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="page-notification">
    + <title>Editing Notifications</title>
    +
    + <figure>
    + <title>The Notification Page</title>
    + <graphic fileref="images/notification_page.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="window-item-new">
    + <title>Creating Items</title>
    +
    + <figure>
    + <title>New Item Window</title>
    + <graphic fileref="images/item_new.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="page-item-icon">
    + <title>Editing Icons</title>
    +
    + <figure>
    + <title>Icon Page</title>
    + <graphic fileref="images/item_icon_page.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="page-item-image">
    + <title>Editing Images</title>
    +
    + <figure>
    + <title>Image Page</title>
    + <graphic fileref="images/item_image_page.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="page-item-text">
    + <title>Editing Text</title>
    +
    + <figure>
    + <title>Text Page</title>
    + <graphic fileref="images/item_text_page.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    +
    + <table>
    + <title>Format Tokens</title>
    +
    + <tgroup cols="2">
    + <tbody valign="top">
    + <row>
    + <entry>%</entry>
    + <entry>A literal '%'</entry>
    + </row>
    + <row>
    + <entry>a</entry>
    + <entry>Account name</entry>
    + </row>
    + <row>
    + <entry>C</entry>
    + <entry>The conversation title</entry>
    + </row>
    + <row>
    + <entry>c</entry>
    + <entry>The conversation name</entry>
    + </row>
    + <row>
    + <entry>D</entry>
    + <entry>Date formatted using the theme option</entry>
    + </row>
    + <row>
    + <entry>d</entry>
    + <entry>The day of the month</entry>
    + </row>
    + <row>
    + <entry>H</entry>
    + <entry>Hour (0-23)</entry>
    + </row>
    + <row>
    + <entry>h</entry>
    + <entry>Hour (0-12)</entry>
    + </row>
    + <row>
    + <entry>i</entry>
    + <entry>Your public IP address</entry>
    + </row>
    + <row>
    + <entry>M</entry>
    + <entry>Month (1-12)</entry>
    + </row>
    + <row>
    + <entry>m</entry>
    + <entry>Minute (0-59)</entry>
    + </row>
    + <row>
    + <entry>N</entry>
    + <entry>Computer name</entry>
    + </row>
    + <row>
    + <entry>n</entry>
    + <entry>Buddy's name (following preferences for aliases)</entry>
    + </row>
    + <row>
    + <entry>p</entry>
    + <entry>Protocol ID</entry>
    + </row>
    + <row>
    + <entry>r</entry>
    + <entry>Received message</entry>
    + </row>
    + <row>
    + <entry>s</entry>
    + <entry>Seconds (0-59)</entry>
    + </row>
    + <row>
    + <entry>T</entry>
    + <entry>Time formatted using the theme option</entry>
    + </row>
    + <row>
    + <entry>t</entry>
    + <entry>Seconds since the epoc</entry>
    + </row>
    + <row>
    + <entry>u</entry>
    + <entry>Computer username</entry>
    + </row>
    + <row>
    + <entry>W</entry>
    + <entry>The name of who warned you (Does this even work?)</entry>
    + </row>
    + <row>
    + <entry>w</entry>
    + <entry>Your warning level or the theme option</entry>
    + </row>
    + <row>
    + <entry>X</entry>
    + <entry>Extra info (needs clarification)</entry>
    + </row>
    + <row>
    + <entry>Y</entry>
    + <entry>Year with century</entry>
    + </row>
    + <row>
    + <entry>y</entry>
    + <entry>Year without century</entry>
    + </row>
    + </tbody>
    + </tgroup>
    + </table>
    + </sect1>
    +
    + <sect1 id="window-delete">
    + <title>Deleting Items and Notifications</title>
    +
    + <figure>
    + <title>Delete Window</title>
    + <graphic fileref="images/item_delete.png" />
    + </figure>
    +
    + <para>
    + 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.
    + </para>
    + </sect1>
    +
    + <sect1 id="saving">
    + <title>Saving</title>
    +
    + <para>
    + 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!
    + </para>
    + </sect1>
    +
    + <sect1 id="Summary">
    + <title>Summary</title>
    +
    + <para>
    + 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>.
    + </para>
    +
    + <para>
    + 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.sf.net">guifications-devel@lists.sf.net</ulink>.
    + </para>
    +
    + <para>
    + I hope this tutorial has been helpful, and as always, thank you for
    + using Guifications.
    + </para>
    + </sect1>
    +</article>
    \ No newline at end of file
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/images/Makefile Sun May 08 08:02:54 2005 +0000
    @@ -0,0 +1,20 @@
    +IMAGES=\
    + item_delete.png \
    + item_icon_page.png \
    + item_image_page.png \
    + item_new.png \
    + item_text_page.png \
    + notification_new.png \
    + notification_page.png \
    + theme_editor.png \
    + theme_info.png \
    + theme_ops.png
    +
    +include ../Makefile.opts
    +
    +all: $(IMAGES)
    + mkdir -p ../$(OUTPUT)/images
    + cp $(IMAGES) ../$(OUTPUT)/images
    +
    +clean:
    +
    Binary file images/item_delete.png has changed
    Binary file images/item_icon_page.png has changed
    Binary file images/item_image_page.png has changed
    Binary file images/item_new.png has changed
    Binary file images/item_text_page.png has changed
    Binary file images/notification_new.png has changed
    Binary file images/notification_page.png has changed
    Binary file images/theme_editor.png has changed
    Binary file images/theme_info.png has changed
    Binary file images/theme_ops.png has changed