[Copyright status: this file is in the public domain.] The ICCCM is the Inter-Client Communications Conventions Manual. It lays out various conventions which, when followed, allow clients from different authors to interact well. These routines are designed to help clients follow ICCCM conventions. lc_icccm_class_hints, lx_icccm_size_hints, lx_icccm_wm_hints, -------------------- ------------------- ----------------- LX_CLASS_HINTS *lx_icccm_class_hints(void) LX_SIZE_HINTS *lx_icccm_size_hints(void) LX_WM_HINTS *lx_icccm_wm_hints(void) These allocate and return structs suitable for ICCCM window-manager hints. They are liblx's analogs of Xlib's XAllocSizeHints(), XAllocWMHints(), and XAllocClassHint(). Each of these may be freed by simply passing it to free(). The returned structs' published fields (not all fields are published; see below) are: LX_CLASS_HINTS: const char *name const char *class This specifies the name and class to be used by other clients when looking up resources for this window (the window manager normally is the only client which wants to do this). LX_SIZE_HINTS: int min_w, int min_h int max_w, int max_h int base_w, int base_h int inc_w, int inc_h int min_a_n, int min_a_d int max_a_n, int max_a_d LX_GRAVITY gravity unsigned int flags; The min_w, min_h, max_w, and max_h fields specify minimum and maximum useful sizes for the window. {base,inc}_{w,h} specify arithmetic progressions of useful sizes: base_D + (i * inc_D), where D is w or h for width or height and i is nonnegative. {min,max}_a_{x,y} specify minimum and maximum useful aspect ratios; aspect ratios are defined as n/d (numerator / denominator) fractions. gravity is one of the LX_GRAVITY_* values, except that Static, Forget, and Unmap are not valid; in the words of the ICCCM (which calls this field "win_gravity"): The window manager will interpret the position of the window, and its border width, to position the point of the outer rectangle of the overall window specified by the win_gravity in the size hints. The outer rectangle of the window includes any borders or decorations supplied by the window manager. In other words, if the window manager decides to place the window where the client asked, the position on the parent window's border named by the win_gravity will be placed where the client window would have been placed in the absence of a window manager. The flags field specifies which of the other values are set LX_S_HINT_MINSIZE min_[wh] LX_S_HINT_MAXSIZE max_[wh] LX_S_HINT_INC inc_[wh] LX_S_HINT_ASPECT {min,max}_a_[nd] LX_S_HINT_BASE base_[wh] LX_S_HINT_GRAVITY gravity and also specifies where the window size and position came from LX_S_HINT_UPOS Position is user-specified LX_S_HINT_USIZE Size is user-specified LX_S_HINT_PPOS Position is program-specified LX_S_HINT_PSIZE Size is program-specified Unfortunately the ICCCM is somewhat broken; it does not define any representation more finely-grained than the above. As two examples, there is no way to specify a minimum aspect ratio without also specifying a maximum; and there is no way to represent user-specified width but program-specified height. This cannot be fixed until the ICCCM is fixed. See also lx_icccm_geometry(), below. If exactly one of LX_S_HINT_MINSIZE and LX_S_HINT_BASE are given, the missing one defaults to the same values as the given one. If LX_S_HINT_GRAVITY is not given, the default is NorthWest. The ICCCM is silent on what happens if there are inconsistencies, such as size or position given as both user-specified and program-specified, or the min/max width/height specifying an aspect ratio outside the aspect ratio limits. liblx does not check for any such cases, simply passing along what it's given. LX_WM_HINTS: LX_XID icon_pix LX_XID icon_mask LX_XID icon_win int icon_x, int icon_y LX_XID group unsigned int flags The icon_pix field specifies a pixmap to be used as an icon. It should be one of the sizes specified in the WM_ICON_SIZE property on the root, if there is such a property, and it should also be 1bpp. (The ICCCM is silent on what is expected to happen if either condition is not satisifed.) icon_mask "specifies which pixels of the icon_pixmap should be used as the icon"; presumably it too should be 1bpp, with 0 bits specifying unused and 1 bits specifying used, but the ICCCM does not say so. icon_win is a window the client wants to be used as an icon. icon_[xy] are a hint to the window manager as to where the client would like its icon placed. (Of course, if the window manager's UI does not have icons, none of the icon_* fields will affect anything.) The group field is used to group together multiple children of the root which should conceptually be treated as a single application. group should be set to the ID of a group leader window (which may be a window that exists solely to be group leader); the group leader's properties are those for the group as a whole (as opposed to individual windows within the group). The flags field specifies which of the other bits are set, and also specifies two things for which there are very few choices. The defined values are: LX_WM_HINT_STATE LX_WM_HINT_STATE_UNSET LX_WM_HINT_STATE_NORMAL LX_WM_HINT_STATE_ICONIC LX_WM_HINT_INPUT LX_WM_HINT_INPUT_UNSET LX_WM_HINT_INPUT_FALSE LX_WM_HINT_INPUT_TRUE LX_WM_HINT_ICONPIXMAP LX_WM_HINT_ICONMASK LX_WM_HINT_ICONWIN LX_WM_HINT_ICONPOS LX_WM_HINT_GROUP LX_WM_HINT_STATE is a multi-bit mask which contains what the ICCCM calls initial_state; these bits must form one of the other LX_WM_HINT_STATE_* values. Except for UNSET, which indicates `not set', these indicate the similarly-named states in the ICCCM model. (The ICCCM model also includes a Withdrawn state, but that is represented by the window being unmapped, not by a value set here.) LX_WM_HINT_INPUT is a multi-bit mask which contains what the ICCCM calls input; the ICCCM's input field is only one bit, but there this field also needs to represent `unset'. FALSE is used for the Globally Active and No Input models, in which the client does not expect the window manager to set the input focus to it; TRUE is used for the Passive and Locally Active models, in which the client does expect that. UNSET, of course, represents `not set'. The other bits indicate whether the various other fields of the LX_WM_HINTS are set. The ICCCM is slightly broken; it has only a single bit for both icon_x and icon_y, with no way to represent states such as "X specified by Y not". This can't be fixed until the ICCCM is fixed. Each of these structs has at least one non-published field as well. All non-published fields are set up appropriately by lx_icccm_*_hints(). These are used by liblx to help deal with version skew between client code, liblx, and window managers. All the non-published fields' names begin with lx__. lx_icccm_geometry ----------------- int lx_icccm_geometry(LX_SIZE_HINTS *sh, const LX_GEOMETRY *g) This sets up sh's LX_S_HINT_[UP]{POS,SIZE} flag bits according to g's flag bits. It does not use anything but the flags field from g and does not use or affect anything but the flags field from sh. The return value is an LX_GEOM_ERR_* value. lx_icccm_wm_properties ---------------------- int lx_icccm_wm_properties( LX_CONN *xc, LX_XID win, const char *wname, const char *iname, int argc, const char * const *argv, LX_SIZE_HINTS *normal_hints, LX_WM_HINTS *wm_hints, LX_CLASS_HINTS *class_hints ) This sets up a minimal set of ICCCM properties on win, using xc. Specifically: - WM_NAME is set to wname. - WM_ICON_NAME is set to iname. - WM_COMMAND is set according to argc and argv. - WM_NORMAL_HINTS is set to normal_hints. - WM_HINTS is set to wm_hints. - WM_CLASS is set to class_hints. - WM_CLIENT_MACHINE is set to the string obtained from gethostname(). If wname, iname, or any of the *_hints arguments is nil, the corresponding property is not set. If argc is less than zero or argv is nil, WM_COMMAND is not set (and the other argument's value is irrelevant). Furthermore, even when WM_COMMAND is being set, argv[argc] is not used and thus does not need to be nil. If class_hints is non-nil but either of its strings is nil, it is as if any nil pointer were a pointer to a valid zero-length string instead. Note that lx_icccm_wm_properties will (in most cases) generate multiple protocol requests. This does not matter in most respects, but it does mean that lx_op_noreply() will return an LX_OP that refers to only the last of those requests, which can matter if an error handler is then attached to it. The argv parameter's type deserves particular note. While it should be consted at both levels, as above, this will demand a cast if you have a char ** value. (char ** and char * const * are compatible, but const char ** and char ** are not. While I can understand this in general, it seems to me there is no danger in adding const, only removing it; perhaps C needs an asymmetric version of compatibility or something. In any case, it does mean that you may need to use a cast for the argv parameter.