diff --git a/ChangeLog b/ChangeLog index 8e27d9223..09bc6febb 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2008-01-21 Thomas Thurman + + * src/ui/theme.[ch]: more commenting. + 2008-01-18 Thomas Thurman * src/ui/theme.[ch]: some more commenting. diff --git a/src/ui/theme.c b/src/ui/theme.c index a31314e4d..57375a04d 100644 --- a/src/ui/theme.c +++ b/src/ui/theme.c @@ -1661,7 +1661,7 @@ debug_print_tokens (PosToken *tokens, * Tokenises an expression. * * \param expr The expression - * \param[out] token_p The resulting tokens + * \param[out] tokens_p The resulting tokens * \param[out] n_tokens_p The number of resulting tokens * \param[out] err set to the problem if there was a problem * @@ -1794,6 +1794,10 @@ pos_tokenize (const char *expr, return FALSE; } +/** + * The type of a PosExpr: either integer, double, or an operation. + * \ingroup parser + */ typedef enum { POS_EXPR_INT, @@ -1802,8 +1806,14 @@ typedef enum } PosExprType; /** + * Type and value of an expression in a parsed sequence. We don't + * keep expressions in a tree; if this is of type POS_EXPR_OPERATOR, + * the arguments of the operator will be in the array positions + * immediately preceding and following this operator; they cannot + * themselves be operators. * * \bug operator is char; it should really be of PosOperatorType. + * \ingroup parser */ typedef struct { @@ -2218,10 +2228,11 @@ pos_eval_get_variable (PosToken *t, * \param n_tokens How many tokens are in the list. * \param env The environment context in which to evaluate the expression. * \param[out] result The current value of the expression + * * \bug Yes, we really do reparse the expression every time it's evaluated. * We should keep the parse tree around all the time and just * run the new values through it. - * \bug FIXME write this + * \ingroup parser */ static gboolean pos_eval_helper (PosToken *tokens, @@ -2398,6 +2409,7 @@ pos_eval_helper (PosToken *tokens, * \return True if we evaluated the expression successfully; false otherwise. * * \bug Shouldn't spec be const? + * \ingroup parser */ static gboolean pos_eval (MetaDrawSpec *spec, @@ -3969,6 +3981,15 @@ meta_draw_op_list_contains (MetaDrawOpList *op_list, return FALSE; } +/** + * Constructor for a MetaFrameStyle. + * + * \param parent The parent style. Data not filled in here will be + * looked for in the parent style, and in its parent + * style, and so on. + * + * \return The newly-constructed style. + */ MetaFrameStyle* meta_frame_style_new (MetaFrameStyle *parent) { @@ -3988,6 +4009,12 @@ meta_frame_style_new (MetaFrameStyle *parent) return style; } +/** + * Increases the reference count of a frame style. + * If the style is NULL, this is a no-op. + * + * \param style The style. + */ void meta_frame_style_ref (MetaFrameStyle *style) { diff --git a/src/ui/theme.h b/src/ui/theme.h index 24927ead5..fce715a8f 100644 --- a/src/ui/theme.h +++ b/src/ui/theme.h @@ -72,6 +72,8 @@ typedef enum /** * Various parameters used to calculate the geometry of a frame. + * They are used inside a MetaFrameStyle. + * This corresponds closely to the tag in a theme file. * * \bug button_sizing isn't really necessary, because we could easily say * that if button_aspect is zero, the height and width are fixed values. @@ -148,12 +150,10 @@ struct _MetaFrameLayout }; /** - * The size of a button (FIXME: In general? Or on one frame?). + * The computed size of a button (really just a way of tying its + * visible and clickable areas together). * The reason for two different rectangles here is Fitts' law & maximized * windows; see bug #97703 for more details. - * - * \bug In general? Or on one frame? FIXME - * \bug Bugs should be hyperlinked: talk to doxygen people */ struct _MetaButtonSpace { @@ -295,33 +295,40 @@ struct _MetaDrawInfo const MetaFrameGeometry *fgeom; }; +/** + * A drawing operation in our simple vector drawing language. + */ typedef enum { - /* Basic drawing */ + /** Basic drawing-- line */ META_DRAW_LINE, + /** Basic drawing-- rectangle */ META_DRAW_RECTANGLE, + /** Basic drawing-- arc */ META_DRAW_ARC, - /* Clip to a rectangle */ + /** Clip to a rectangle */ META_DRAW_CLIP, /* Texture thingies */ - META_DRAW_TINT, /* just a filled rectangle with alpha */ + + /** Just a filled rectangle with alpha */ + META_DRAW_TINT, META_DRAW_GRADIENT, META_DRAW_IMAGE, - /* GTK theme engine stuff */ + /** GTK theme engine stuff */ META_DRAW_GTK_ARROW, META_DRAW_GTK_BOX, META_DRAW_GTK_VLINE, - /* App's window icon */ + /** App's window icon */ META_DRAW_ICON, - /* App's window title */ + /** App's window title */ META_DRAW_TITLE, - /* a draw op list */ + /** a draw op list */ META_DRAW_OP_LIST, - /* tiled draw op list */ + /** tiled draw op list */ META_DRAW_TILE } MetaDrawType; @@ -347,6 +354,11 @@ typedef enum POS_OP_MIN } PosOperatorType; +/** + * A token, as output by the tokeniser. + * + * \ingroup tokenizer + */ typedef struct { PosTokenType type; @@ -374,11 +386,14 @@ typedef struct } PosToken; /** + * A computed expression in our simple vector drawing language. + * While it appears to take the form of a tree, this is actually + * merely a list; concerns such as precedence of operators are + * currently recomputed on every recalculation. * * Created by meta_draw_spec_new(), destroyed by meta_draw_spec_free(). * pos_eval() fills this with ...FIXME. Are tokens a tree or a list? - * \bug FIXME finish filling this in - * \ingroup tokenizer + * \ingroup parser */ typedef struct _MetaDrawSpec { @@ -397,7 +412,10 @@ typedef struct _MetaDrawSpec /** Does the expression contain any variables? */ gboolean constant : 1; } MetaDrawSpec; - + +/** + * A single drawing operation in our simple vector drawing language. + */ struct _MetaDrawOp { MetaDrawType type; @@ -543,6 +561,14 @@ struct _MetaDrawOp } data; }; +/** + * A list of MetaDrawOp objects. Maintains a reference count. + * Grows as necessary and allows the allocation of unused spaces + * to keep reallocations to a minimum. + * + * \bug Do we really win anything from not using the equivalent + * GLib structures? + */ struct _MetaDrawOpList { int refcount; @@ -636,16 +662,39 @@ typedef enum } MetaFramePiece; #define N_GTK_STATES 5 + +/** + * How to draw a frame in a particular state (say, a focussed, non-maximised, + * resizable frame). This corresponds closely to the tag + * in a theme file. + */ struct _MetaFrameStyle { + /** Reference count. */ int refcount; + /** + * Parent style. + * Settings which are unspecified here will be taken from there. + */ MetaFrameStyle *parent; + /** Operations for drawing each kind of button in each state. */ MetaDrawOpList *buttons[META_BUTTON_TYPE_LAST][META_BUTTON_STATE_LAST]; + /** Operations for drawing each piece of the frame. */ MetaDrawOpList *pieces[META_FRAME_PIECE_LAST]; + /** + * Details such as the height and width of each edge, the corner rounding, + * and the aspect ratio of the buttons. + */ MetaFrameLayout *layout; - MetaColorSpec *window_background_color; /* can be NULL to use the standard - GTK theme engine */ - guint8 window_background_alpha; /* 0=transparent; 255=opaque */ + /** + * Background colour of the window. Only present in theme formats + * 2 and above. Can be NULL to use the standard GTK theme engine. + */ + MetaColorSpec *window_background_color; + /** + * Transparency of the window background. 0=transparent; 255=opaque. + */ + guint8 window_background_alpha; }; /* Kinds of frame... @@ -688,7 +737,17 @@ typedef enum META_FRAME_FOCUS_LAST } MetaFrameFocus; -/* One StyleSet per window type (for window types that get a frame) */ +/** + * How to draw frames at different times: when it's maximised or not, shaded + * or not, when it's focussed or not, and (for non-maximised windows), when + * it can be horizontally or vertically resized, both, or neither. + * Not all window types actually get a frame. + * + * A theme contains one of these objects for each type of window (each + * MetaFrameType), that is, normal, dialogue (modal and non-modal), etc. + * + * This corresponds closely to the tag in a theme file. + */ struct _MetaFrameStyleSet { int refcount; @@ -699,20 +758,47 @@ struct _MetaFrameStyleSet MetaFrameStyle *maximized_and_shaded_styles[META_FRAME_FOCUS_LAST]; }; +/** + * A theme. This is a singleton class which groups all settings from a theme + * on disk together. + * + * \bug It is rather useless to keep the metadata fields in core, I think. + */ struct _MetaTheme { + /** Name of the theme (on disk), e.g. "Crux" */ char *name; + /** Path to the files associated with the theme */ char *dirname; + /** + * Filename of the XML theme file. + * \bug Kept lying around for no discernable reason. + */ char *filename; + /** Metadata: Human-readable name of the theme. */ char *readable_name; + /** Metadata: Author of the theme. */ char *author; + /** Metadata: Copyright holder. */ char *copyright; + /** Metadata: Date of the theme. */ char *date; + /** Metadata: Description of the theme. */ char *description; + /** Version of the theme format. Older versions cannot use the features + * of newer versions even if they think they can (this is to allow forward + * and backward compatibility. + */ guint format_version; + /** Symbol table of integer constants. */ GHashTable *integer_constants; + /** Symbol table of float constants. */ GHashTable *float_constants; + /** + * Symbol table of colour constants (hex triples, and triples + * plus alpha). + * */ GHashTable *color_constants; GHashTable *images_by_filename; GHashTable *layouts_by_name;