nub.h

Go to the documentation of this file.

#ifndef NUB_CLASS
#define NUB_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : nub                                                               *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*  Purpose:                                                                   *
*                                                                             *
*    This class is the root of all objects that must interact with the        *
*  windowing system.                                                          *
*                                                                             *
*******************************************************************************
* Copyright (c) 1991-$now By Author.  This program is free software; you can  *
* redistribute it and/or modify it under the terms of the GNU General Public  *
* License as published by the Free Software Foundation; either version 2 of   *
* the License or (at your option) any later version.  This is online at:      *
*     http://www.fsf.org/copyleft/gpl.html                                    *
* Please send any updates to: fred@gruntose.com                               *
\*****************************************************************************/

#include "argument_list.h"
#include "definitions_passive.h"

#include <geometric/cartesian_objects.h>

// forward.
class color;

class WP_PASSIVE_CLASS_STYLE nub
{
public:
  nub(window_handle parent, window_handle self);
    // Creates a nodule for interacting with the windowing system.  "parent"
    // must be a valid, non-NIL window handle.  "self" may be NIL, but must
    // be filled in before any function in nub is called.  If parent and
    // self are identical, then the nub is assumed to be either: 1) one for
    // which only one window_handle is known or 2) the root window_handle.
    // If the two handles are identical, then the self's corresponding
    // windowing system object is NOT destroyed when the nub is destructed.

  ~nub();

  window_handle self() const;
    // Returns the underlying window_handle encapsulated by "this".  This is
    // the only function involving the "self" window_handle that does not
    // abort if self is NIL.  This means that it must be checked first for
    // being NIL unless one is definite that self is already non-NIL.

  window_handle parent() const;
    // Returns the parent of this nub.

  c_rectangle device_dimensions() const;
    // Returns a rectangle bounding the nub by querying the windowing system
    // regarding the object's size.  This will only work if the object has
    // already been created (self is non-NIL) and mapped to the screen.
    // The returned rectangle is currently relative to the outermost containing
    // window's origin.  The fact that it is relative unfortunately means that
    // if that outermost window's dimensions are asked for, then its origin
    // will be reported as zero.

  void device_dimensions(const c_rectangle &new_size);
    // Sets the size of the nub's associated object in device coordinates.
    // This assumes that the first vertex of the rectangle (taken as the
    // origin of the rectangle) is ordered in accordance with the device
    // coordinate system.  If the two vertices are identical, then only
    // the origin of the nub is set.

  // The following functions retrieve underlying windowing system information
  // concerning the window handle encapsulated by this nub.

#ifdef __XWINDOWS__
  Display *display();
  Visual *visual();
  Window window();
  int screen();

  bool realized() const;
    // reports whether the nub is actually on the screen yet or not.
  void realize();
    // tells the nub to set itself up.  all pertinent preconditions should
    // be satisfied (e.g., the self exists and has been configured).

  void disengage();
  void engage();
    // Needed within __XWINDOWS__ to disconnect a widget from its parent so that
    // the callbacks on the widget will not be invoked (the parent performs
    // no management on the child when it is disengaged).

  void map();
  void unmap();
    // Places a previously existing window back on the screen or removes the
    // window from the screen, respectively.

  void add_dimensions(argument_list &to_add_to, const c_rectangle &size);
    // Used to update an argument list with the necessary commands to cause
    // a window to be at a particular origin and to possess a particular size.
    // The "size" is a rectangle measured in device coordinates which should
    // be aligned appropriately with the device coordinate system.

  void add_origin(argument_list &wargs, const c_point &origin);
    // adds only the origin to an argument list.

  void set_foreground(const color &new_foreground);
  void set_background(const color &new_background);

private:
  bool i_am_realized;

#elif defined(OS_2)
#elif defined(MS_WINDOWS)
#endif

protected:
  void self(window_handle to_set);
    // resets the handle encapsulated in "this".

  void parent(window_handle w);
    // resets the parent window_handle.

private:
  window_handle _parent;
  window_handle _self;
};

#endif

---