.. _gui_structure:

GUI structure
-------------

.. structure:: GUI

    This object is created with the :func:`GUI(width,height)` function.

    A GUI object is a kind of :struct:`Box` that is the outermost
    window that holds all the other widgets.  In order to work at all, all
    widgets must be put inside of a ``GUI`` box, or in inside of another
    :struct:`Box` which in turn is inside a ``GUI`` box, etc.

    (To get rid of all GUIs that you created from this CPU, you can use
    the :func:`CLEARGUIS` built-in-function, which is a shorthand
    for calling :attr:`Widget:HIDE` and :attr:`Widget:DISPOSE` on each
    of them.)

    ===================================== =============================== =============
    Suffix                                Type                            Description
    ===================================== =============================== =============
       Every suffix of :struct:`BOX`.  Note, to add widgets to this window, see the BOX suffixes.
    -----------------------------------------------------------------------------------
    :attr:`X`                             :struct:`scalar` (pixels)       X-position of the window. Negative values measure from the right.
    :attr:`Y`                             :struct:`scalar` (pixels)       Y-position of the window. Negative values measure from the bottom.
    :attr:`DRAGGABLE`                     :struct:`Boolean`               True = user can move window.
    :attr:`EXTRADELAY`                    :struct:`scalar` (seconds)      Add artificial delay to all communication with this GUI (good for testing before you get into deep space)
    :attr:`SKIN`                          :struct:`Skin`                  The skin defining the default style of widgets in this GUI.
    :meth:`SHOW`                          none                            Call to make the gui appear
    :meth:`HIDE`                          none                            Call to make the gui disappear
    ===================================== =============================== =============

    .. attribute:: X

        :type: :struct:`scalar`
        :access: Get/Set

        This is the X position of upper-left corner of window, in pixels.

        You can alter this value to move the window.

        If you use a negative value for the coordinate, then the coordiante will be
        measured in the reverse direction, from the right edge of the screen.  (i.e.
        setting it to -200 means 200 pixels away from the right edge of the screen.)

    .. attribute:: Y

        :type: :struct:`scalar`
        :access: Get/Set

        This is the Y position of upper-left corner of window, in pixels.

        You can alter this value to move the window.

        If you use a negative value for the coordinate, then the coordiante will be
        measured in the reverse direction, from the bottom edge of the screen.  (i.e.
        setting it to -200 means 200 pixels away from the bottom edge of the screen.)

    .. attribute:: DRAGGABLE

        :type: :struct:`Boolean`
        :access: Get/Set

        Set to true to allow the window to be moved by the user dragging it.  If
        set to false, it can still be moved by the script setting :attr:`GUI:X`
        and :attr:`GUI:Y`, but can't be moved by the user.

    .. attribute:: EXTRADELAY

        :type: :struct:`scalar`
        :access: Get/Set

        This is the number of extra seconds of delay to add to
        the GUI for testing purposes.

        If Remote Tech is installed, the GUI system :ref:`obeys the signal delay<gui_delay>`
        of the Remote Tech mod such that when you click a widget it can take
        time before the script notices you did so.  If you want to test how
        your GUI will work under a signal delay you can use this suffix to
        force a simulated additional signal delay even if you are not using
        RemoteTech.  (Or when you are using RemoteTech but are testing your GUI in
        situations where there isn't a noticable signal delay, like in Kerbin
        low orbit).

    .. attribute:: SKIN

        :type: :struct:`Skin`
        :access: Get/Set

        A :struct:`Skin` is a collection of :struct:`Style` objects to be
        used by different types of widgets within the GUI window.  With this
        suffix you can assign a different Skin to the window, which will then
        be used by default by all the widgets of the appropriate type
        inside the window.

    .. method:: SHOW

        Synopsis::

            set g to gui(200).
            // .. call G:addbutton, G:addslider, etc etc here
            g:show().

        Call this suffix to make the GUI appear.  (Note this is really just
        :meth:`Widget:Show` but it's mentioned again here because it's
        vital when making a GUI to know that it won't show up if you don't
        call this.)

    .. method:: HIDE

        Synopsis::

            set g to gui(200).
            // .. call G:addbutton, G:addslider, etc etc here
            g:show().
            wait until done. // whatever you decide "done" is.
            g:hide().

        Call this suffix to make the GUI disappear.  (Note this is really just
        :meth:`Widget:Show` but it's mentioned again here.)