Actually drawing stuff
frame_style: This is probably the most complicated part of the whole system. A frame_style a series of pieces and buttons. It looks like this:
<frame_style name="…" geometry="G"> <piece position="P"> <draw_ops> </draw_ops> </piece> … <button function="F" state="S" draw_ops="D"/> <draw_ops> </draw_ops> </button> … </frame_style>
The pieces are pieces of the window frame. When Metacity draws a window frame, it renders its various pieces always in the same order. The bolded parts are all the possible values of P:
- the entire_background, covering the whole frame
- the titlebar, covering the entire background of the titlebar
- the titlebar_middle, the part of the titlebar that doesn't touch its edges
- the left_titlebar_edge, right_titlebar_edge, top_titlebar_edge, and bottom_titlebar_edge
- the title, just exactly that area which is covered by the text on the titlebar
- the left_edge, right_edge, and bottom_edge of the frame (yes, there is no top_edge: it's identical to top_titlebar_edge, isn't it?)
- the overlay, which covers everything– the same as entire_background, but done last instead of first.
What Metacity draws in these pieces is decided by the theme. If a frame_style or its parents don't specify a particular piece, nothing will be drawn for that piece. You have two ways to specify what to draw: one is that the piece tag can have a draw_ops tag inside it which lists a sequence of drawing operations in Metacity's custom format. You might ask why we don't use SVG; one answer is that SVG support wasn't very strong when this format was designed, and another answer is that these days you can use SVG all you like; just include it as an image and Metacity will know what to do.
An alternative to including a draw_ops tag inside a piece tag is to add a draw_ops attribute to the piece tag. Then you can add a draw_ops tag at top level (inside the metacity_theme tag) with a name attribute, and Metacity will use that. This is useful if you use similar draw_ops over and over.
I'm not going to document draw_ops at present, because this is already very long. I will write it up later and link it from here.
The button tag tells Metacity how, but not where, to draw buttons. Buttons are drawn after all the pieces are finished, and the way to draw them is also given using draw_ops. You ought to provide buttons for all the possible kinds of button; if you don't give one it won't be drawn, which is unfortunate for the user who wants to use it:
- left_left_background, left_middle_background, and left_right_background don't represent buttons as such, but the background behind them, assuming there can be at most three buttons on the left. These days there can be more, so the extra ones also use left_middle_background.
- right_left_background, right_middle_background, and right_right_background similarly.
- close, minimize, maximize are the obvious original three buttons.
- menu is the menu button you can click to get a list of actions you can perform on the window.
- shade, above, stick are similar to the original buttons but only allowed in version 2
- unshade, unabove, unstick are the toggled versions of these buttons. Again, version 2 only.
The reason there are toggled versions of shade, above, and stick, and not maximize, is that by the time you get this far you've probably already decided whether you're drawing a maximised window. So if you are drawing a maximised window, you can make the button called "maximize" look how you want the restore button to be; otherwise, make it look like you want the maximise button to be.
For each button tag you should also set a "state" attribute; this time the state is either normal (the way you see it most of the time), pressed, or prelight (this makes the buttons subtly light up when you hover over them). You only really need "normal", but the others are good to have too.
The "geometry" attribute of a frame_style tag is the name of a…