constants.h

The major functionality added in this release includes: - Rootless mode in X11 - Widget Templt

/* $Id: constants.h,v 1.172 2002/11/15 12:53:11 micahjd Exp $
 *
 * picogui/constants.h - various constants needed by client, server,
 *                       and application
 *
 * PicoGUI small and efficient client/server GUI
 * Copyright (C) 2000-2002 Micah Dowty <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 * 
 * Contributors:
 * 
 * 
 * 
 */

#ifndef _H_PG_CONSTANTS
#define _H_PG_CONSTANTS

/*! 
 * \file constants.h
 * \brief Constants used in the client and server
 * 
 * This file defines constants common to the PicoGUI client and the server.
 * Because the most interesting things in PicoGUI like widgets and gropnodes
 * are referred to using constants, they are documented in this file.
 * 
 * Usually this file does not need to be included
 * separately, it is included with <tt>\#include <picogui.h></tt>
 */

/*!
 * \defgroup constants Constants
 * 
 * These constants are used in both the PicoGUI client and the server.
 * They are defined in constants.h
 * 
 * \{
 */

/* Just to make sure... */
#ifndef NULL
#define NULL ((void*)0)
#endif

/******************** Keyboard constants */

/* Lots of these, so use a seperate file... */
#include <picogui/pgkeys.h>

/******************** Application manager */

/*!
 * \defgroup appconst Application registration constants
 * 
 * These constants are used with pgRegisterApp() to create
 * a new application
 * 
 * \{
 */

#define PG_APP_NORMAL   1     //!< Normal application for pgRegisterApp
#define PG_APP_TOOLBAR  2     //!< Toolbar application for pgRegisterApp
#define PG_APPMAX       2     //!< Current maximum value used in PG_APP_* constants

#define PG_APPSPEC_SIDE      1    //!< Force the app to a specified side
#define PG_APPSPEC_SIDEMASK  2    //!< A bitmask of acceptable sides for an application
#define PG_APPSPEC_WIDTH     3    //!< Requested width
#define PG_APPSPEC_HEIGHT    4    //!< Requested height

#define PG_APPSPEC_MINWIDTH  5    //!< Minimum allowed width
#define PG_APPSPEC_MAXWIDTH  6    //!< Maximum allowed width
#define PG_APPSPEC_MINHEIGHT 7    //!< Minimum allowed height
#define PG_APPSPEC_MAXHEIGHT 8    //!< Maximum allowed height

#define PG_OWN_DISPLAY       4    //!< Exclusive access to the display via pgRender

//! \}

/******************** Layout */

/*!
 * \defgroup layoutconst Layout constants
 * 
 * PicoGUI defines two types of layout constants:
 *  - PG_A_* constants define alignment, the way a smaller object is positioned
 *    within a larger one, usually without changing the smaller object's size.
 *    For example, placing text within a widget.
 *  - PG_S_* constants specify a side to attach something to, for example the
 *    side of a container that a widget will stick to
 *
 * The side flags can be combined with a bitwise 'or' if necessary.
 * The values of the PG_S_* constants are significant because they must
 * be compatible with the server's internal layout engine flags.
 * 
 * \sa PG_WP_SIDE, PG_WP_ALIGN
 *
 * \{
 */

/* Alignment types */
#define PG_A_CENTER   0  //!< Center in the available space
#define PG_A_TOP      1  //!< Stick to the top-center of the available space
#define PG_A_LEFT     2  //!< Stick to the left-center of the available space
#define PG_A_BOTTOM   3  //!< Stick to the bottom-center of the available space
#define PG_A_RIGHT    4  //!< Stick to the right-center of the available space
#define PG_A_NW       5  //!< Stick to the northwest corner
#define PG_A_SW       6  //!< Stick to the southwest corner
#define PG_A_NE       7  //!< Stick to the northeast corner
#define PG_A_SE       8  //!< Stick to the southeast corner
#define PG_A_ALL      9  //!< Occupy all available space (good for tiled bitmaps)
#define PG_AMAX       9  //!< Current maximum value for a PG_A_* constant 

#define PG_S_TOP      (1<<3)   //!< Stick to the top edge
#define PG_S_BOTTOM   (1<<4)   //!< Stick to the bottom edge
#define PG_S_LEFT     (1<<5)   //!< Stick to the left edge
#define PG_S_RIGHT    (1<<6)   //!< Stick to the right edget
#define PG_S_ALL      (1<<11)  //!< Occupy all available space

//! \}

/******************** Fonts */

/*!
 * \defgroup fontconst Font styles
 * 
 * These font style constants can be used as the \p flags parameter of
 * pgFindFont() to specify font attributes.
 * 
 * These constants can also be used when defining a new font for pgserver:
 *   - PG_FSTYLE_FIXED
 *   - PG_FSTYLE_DEFAULT
 *   - PG_FSTYLE_SYMBOL
 *   - PG_FSTYLE_SUBSET
 *   - PG_FSTYLE_ENCODING_ISOLATIN1
 *   - PG_FSTYLE_ENCODING_IBM
 *   - PG_FSTYLE_ENCODING_UNICODE
 * 
 * \{
 */

#define PG_FSTYLE_FIXED        (1<<0)    //!< Fixed width
#define PG_FSTYLE_DEFAULT      (1<<1)    //!< The default font in its category, fixed or proportional.
#define PG_FSTYLE_SYMBOL       (1<<2)    //!< Font contains nonstandard chars and will not be chosen unless specifically requested
#define PG_FSTYLE_SUBSET       (1<<3)    //!< Font does not contain all the ASCII chars before 127, and shouldn't be used unless requested
#define PG_FSTYLE_ENCODING_ISOLATIN1  (1<<4)  //!< ISO Latin-1 encoding
#define PG_FSTYLE_ENCODING_IBM        (1<<5)  //!< IBM-PC extended characters
#define PG_FSTYLE_DOUBLESPACE  (1<<7)    //!< Add extra space between lines
#define PG_FSTYLE_BOLD         (1<<8)    //!< Use or simulate a bold version of the font
#define PG_FSTYLE_ITALIC       (1<<9)    //!< Use or simulate an italic version of the font
#define PG_FSTYLE_UNDERLINE    (1<<10)   //!< Underlined text
#define PG_FSTYLE_STRIKEOUT    (1<<11)   //!< Strikeout, a line through the middle of the text
#define PG_FSTYLE_GRAYLINE     (1<<12)   //!< deprecated
#define PG_FSTYLE_FLUSH        (1<<14)   //!< Disable the margin that PicoGUI puts around text
#define PG_FSTYLE_DOUBLEWIDTH  (1<<15)   //!< Add extra space between characters
#define PG_FSTYLE_ITALIC2      (1<<16)   //!< Twice the slant of the default italic
#define PG_FSTYLE_ENCODING_UNICODE    (1<<17) //!< Unicode encoding
#define PG_FSTYLE_CONDENSED    (1<<18)   //!< Condensed width

#define PG_FSTYLE_ENCODING_MASK       (PG_FSTYLE_ENCODING_ISOLATIN1|\
                                       PG_FSTYLE_ENCODING_IBM|\
                                       PG_FSTYLE_ENCODING_UNICODE)

/* Styles that are part of the font, rather than how it's rendered */
#define PG_FSTYLE_STYLE_MASK          (PG_FSTYLE_BOLD|\
                                       PG_FSTYLE_ITALIC|\
                                       PG_FSTYLE_CONDENSED)

/* Styles that shouldn't be used unless requested */
#define PG_FSTYLE_TYPE_MASK          (PG_FSTYLE_SUBSET|\
                                      PG_FSTYLE_SYMBOL)

//! \}

/*!
 * \defgroup fontrep Font representations
 * 
 * These flags can be returned by pgGetFontStyle, indicating supported
 * methods of graphically representing a font.
 *
 * Currently this can only indicate whether a font has built-in bold, italic,
 * or bolditalic bitmaps, but in the future could be used to indicate whether
 * a style is bitmapped or scalable.
 * 
 * \{
 */

#define PG_FR_BITMAP_NORMAL        (1<<0)    //!< Normal bitmapped font
#define PG_FR_BITMAP_BOLD          (1<<1)    //!< Bitmapped font with bold
#define PG_FR_BITMAP_ITALIC        (1<<2)    //!< Bitmapped font with italic
#define PG_FR_BITMAP_BOLDITALIC    (1<<3)    //!< Bitmapped font with bold and italic
#define PG_FR_SCALABLE             (1<<4)    //!< TrueType, Type1, or other outline font

//! \}

/******************** Errors */

/*! 
 * \defgroup errconst Error types
 * 
 * These error types are passed to the error handler
 * when the client or server triggers an error.
 * 
 * \sa pgSetErrorHandler
 * 
 * \{
 */
#define PG_ERRT_NONE     0x0000    //!< No error condition
#define PG_ERRT_MEMORY   0x0100    //!< Error allocating memory
#define PG_ERRT_IO       0x0200    //!< Filesystem, operating system, or other IO error
#define PG_ERRT_NETWORK  0x0300    //!< Network (or IPC) communication error */
#define PG_ERRT_BADPARAM 0x0400    //!< Invalid parameters */
#define PG_ERRT_HANDLE   0x0500    //!< Invalid handle ID, type, or ownership
#define PG_ERRT_INTERNAL 0x0600    //!< Shouldn't happen (tell a developer!)
#define PG_ERRT_BUSY     0x0700    //!< Try again later?
#define PG_ERRT_FILEFMT  0x0800    //!< Error in a loaded file format (theme files, bitmaps)

#define PG_ERRT_CLIENT   0x8000    //!< An error caused by the client lib, not the server

//! \}

/******************** Handles */

/*!
 * \defgroup handletypes Handle types
 * \{
 */

/*!
 * \brief PicoGUI handle data type
 * 
 * A handle is an arbitrary number that refers to an object stored in the
 * PicoGUI server's memory. All handles have a type, all handles can be
 * deleted, and all handles can store a payload.
 * 
 * \sa pgDelete, PG_ERRT_HANDLE, pgSetPayload, pgGetPayload
 */
typedef unsigned long pghandle;

/* Data types */
#define PG_TYPE_BITMAP     1    //!< Created by pgNewBitmap()
#define PG_TYPE_WIDGET     2    //!< Created by pgNewWidget(), pgNewPopup(), pgNewPopupAt(), or pgRegisterApp()
#define PG_TYPE_FONTDESC   3    //!< Created by pgNewFont()
#define PG_TYPE_PGSTRING   4    //!< Created by pgNewString()
#define PG_TYPE_THEME      5    //!< Created by pgLoadTheme()
#define PG_TYPE_FILLSTYLE  6    //!< Used internally to store a theme's fillstyles
#define PG_TYPE_ARRAY      7    //!< Created by pgNewArray()
#define PG_TYPE_DRIVER     8    //!< Created by pgLoadDriver()
#define PG_TYPE_PALETTE    9    //!< An array of pgcolors, transformed into hwrcolors
#define PG_TYPE_WT         11   //!< Created by pgLoadWidgetTemplate
#define PG_TYPE_INFILTER   12   //!< One filter in the input filter chain
#define PG_TYPE_CURSOR     13   //!< Cursor object, used with input filters
#define PG_TYPE_PARAGRAPH  14   //!< A paragraph (wrapped text) 
#define PG_TYPE_DIVTREE    15   //!< Tree of divnodes, one layer of nonoverlapping items

/* Also add new handle types to the debug code in handle.c, r_handle_dump() */

#define PG_TYPEMASK        0x1F

//! \}

/******************** Theme constants */

/*!
 * \defgroup themeconst Theme constants
 * 
 * Themes in PicoGUI make use of many types of constants. Theme objects,
 * properties, tags, loaders, and opcodes are described in this section.
 * 
 * \{
 */

/*! 
 * \defgroup thobj Theme objects
 * 
 * Theme objects: they don't have to correspond to widgets or anything
 * else in PicoGUI, although they usually do.
 * A widget can have more than one theme object, or
 * theme objects can be used for things that aren't widgets, etc...
 *
 * A theme object is just a category to place a list of properties in,
 * but theme objects inherit properties from other theme objects
 * according to a built in hierarchy
 *
 * As a naming convention, these constants should start with PGTH_O_ and
 * after that use underscores to represent subclassing. Bases are omitted
 * from names (otherwise they would be much longer, and if extra bases
 * were added the names would become misleading) so they don't strictly
 * follow the inheritance flow. The theme compiler uses '.' to subclass
 * (for us C weenies) so what is PGTH_O_FOO_MUMBLE is foo.mumble
 * in the theme compiler.
 * 
 * \{
 */

#define PGTH_O_DEFAULT               0    //!< Every theme object inherits this 
#define PGTH_O_BASE_INTERACTIVE      1    //!< Base for interactive widgets 
#define PGTH_O_BASE_CONTAINER        2    //!< Base for containers like toolbars 
#define PGTH_O_BUTTON                3    //!< The button widget 
#define PGTH_O_BUTTON_HILIGHT        4    //!< Button, hilighted when mouse is over