LibGGIWmh Functions
===================



Initialize and Uninitialize LibGGIWmh
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWmhInit ggiWmhExit ggiWmhAttach ggiWmhDetach


Synopsis
--------

::

  #include <ggi/wmh.h>

  int ggiWmhInit(void);

  int ggiWmhExit(void);

  int ggiWmhAttach(ggi_visual_t vis);

  int ggiWmhDetach(ggi_visual_t vis);


Description
-----------

These are the standard LibGGI extension management functions for the
LibGGIWmh extension. They allow initialization and deinitialization
of the extension as a whole and of individual visuals.

`ggiWmhInit` will initialize an instance of the LibGGIWmh extension and
prepare it to attach to visuals.

`ggiWmhAttach`, if successful, will allow LibGGIWmh functions to
operate on the named visual.

`ggiWmhDetach`, if successful, will clean up all resources involved in
providing the named visual with the LibGGIWmh API.

`ggiWmhExit` will free all resources associated with an instance of
LibGGIWmh.


Return value
------------

`ggiWmhInit` returns `0` for OK, otherwise an :man:`ggi-error(3)` code.


`ggiWmhExit` returns:

`0`
    after successfully cleaning up,

`>0`
    the number of 'open' `ggiWmhInit` calls, if there has been more than
    one call to `ggiWmhInit`. As `ggiWmhInit` and `ggiWmhExit` must be
    used in properly nested pairs, e.g. the first `ggiWmhExit` after two
    `ggiWmhInit`'s will return `1`.

`<0`
    :man:`ggi-error(3)`, especially if more `ggiWmhExit` calls have been done than
    `ggiWmhInit` calls.


`ggiWmhAttach` returns:

`>=0`
    the number LibGGIWmh has been attached to this visual, whereas
    0 means the first time.

`<0`
    indicates an :man:`ggi-error(3)`.


`ggiWmhDetach` returns:

`0`
    after successfully cleaning up,

`>0`
    the number of 'open' `ggiWmhAttach` calls, if there has been more than
    one call to `ggiWmhAttach`. As `ggiWmhAttach` and `ggiWmhDetach` must be
    used in properly nested pairs, e.g. the first `ggiWmhDetach` after two
    `ggiWmhInit`s will return `1`.

`<0`
    :man:`ggi-error(3)`, especially if more `ggiWmhDetach` calls have been
    done than `ggiWmhAttach` calls.


Examples
--------

::

  ggi_visual_t vis;

  ggiInit();
  ggiWmhInit();
  vis = ggiOpen(NULL);
  ggiWmhAttach(vis);

  /* ... */

  ggiWmhDetach(vis);
  ggiWmhExit();
  ggiExit();



Moving and Resizing Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWmhMove ggiWmhGetPos ggiWmhResize ggiWmhGetSize ggiWmhAllowResize ggiWmhMaximize


Synopsis
--------

::

  #include <ggi/wmh.>

  int ggiWmhMove(ggi_visual_t vis, int x, int y);

  int ggiWmhGetPos(ggi_visual_t vis, int *x, int *y);

  int ggiWmhResize(ggi_visual_t vis, int x, int y);

  int ggiWmhGetSize(ggi_visual_t vis, int *x, int *y);

  int ggiWmhAllowResize(ggi_visual_t vis,int xmin,int ymin,
                        int xmax,int ymax,int xstep,int ystep);

  int ggiWmhMaximize(ggi_visual_t vis,int xperc,int yperc);


Description
-----------

`ggiWmhMove` moves the window to the specified :p:`x`, :p:`y` position, where
:p:`x`,:p:`y` specifies the top-left corner.

`ggiWmhGetPos` returns the window position, whereas
:p:`x`, :p:`y` specifies the top-left corner.

`ggiWmhResize` resizes the window, whereas :p:`x`, :p:`y` specifies the
new width and height.

`ggiWmhGetSize` returns the window size, whereas :p:`x`, :p:`y` specifies
the window width and height.

`ggiWmhAllowResize` enables the window attributes to allow
resizing. :p:`xmin`, :p:`ymin` specifies the minimized window width and height.
:p:`xmax`, :p:`ymax` specifies the maximized window width and height.
:p:`xstep`, :p:`ystep` specifies the resizing steps.

`ggiWmhMaximize` maximizes the window. :p:`xperc` is the horizontal
percentage of the screen width and :p:`yperc` is the vertical
percentage of the screen height.


Return values
-------------

All six return `0` for success and an :man:`ggi-error(3)` code on failure.


See Also
--------

:man:`ggiWmhSetTitle(3)`



Set the window title
~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWmhSetTitle


Synopsis
--------

::

  #include <ggi/wmh.h>

  int ggiWmhSetTitle(ggi_visual_t vis, const char *title);



Description
-----------

`ggiWmhSetTitle` sets a new title to the window.


Return value
------------

`ggiWmhSetTitle` returns `0` for success, otherwise an :man:`ggi-error(3)`
code on failure.


See Also
--------

:man:`ggiWmhMove(3)`



Raising and lowering a window
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWmhZOrder


Synopsis
--------

::

  #include <ggi/wmh.h>

  int ggiWmhZOrder(ggi_visual_t vis,enum ggi_wmh_ordercmd command);


Description
-----------

`ggiWmhZOrder` raises windows up or lowers down as specified
in the :p:`command` arg:

`GGI_WMH_ZO_TOP` raises the window to the top. It overlaps all windows,
including non-GGI ones.

`GG_WMH_ZO_BOTTOM` puts the window to the bottom. All other windows,
including non-GGI ones, overlap it.

`GGI_WMH_ZO_ONE_UP`, `GGI_WMH_ZO_ONE_DOWN` raises or lowers the window one
level up or down.

.. important::
   The ZO_* are deprecated and are going to be removed. They are just
   aliases for the new ones to allow users a smooth migration.


Return value
------------

`ggiWmhZOrder` returns `0` for success, otherwise an :man:`ggi-error(3)`
code on failure.



Modify Icon handling
~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWmhIconify ggiWmhMoveIcon ggiWmhSetIconTitle


Synopsis
--------

::

  #include <ggi/wmh.>

  int ggiWmhIconify      (ggi_visual_t vis,int icon);

  int ggiWmhMoveIcon     (ggi_visual_t vis,int x,int y);

  int ggiWmhSetIconTitle (ggi_visual_t vis, const char *title);


Description
-----------

`ggiWmhIconify` switches the window into one of three different
states according to the :p:`icon` argument: 

  `GGI_WMH_MAPSTATE_NORMAL`: Normal state. 
  
  `GGI_WMH_MAPSTATE_ICON`: Iconified state.
  
  `GGI_WMH_MAPSTATE_WITHDRAWN`: Withdrawn state (invisible).

`ggiWmhMoveIcon` moves the icon to the position, where
:p:`x`, :p:`y` specifies the top-left icon corner.

`ggiWmhSetIconTitle` sets the name to be displayed in a window's
icon.


Return value
------------

All three functions return `0` for success, otherwise an :man:`ggi-error(3)`
code on failure.
