SoGuiComponentCommon.cpp.in

// @configure_input@

/**************************************************************************\
 * Copyright (c) Kongsberg Oil & Gas Technologies AS
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 * 
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * 
 * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * 
 * Neither the name of the copyright holder nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\**************************************************************************/

/*!
  \class So@Gui@Component So@Gui@Component.h Inventor/@Gui@/So@Gui@Component.h
  \brief The So@Gui@Component class is the base class for all GUI components.

  Components in the So@Gui@ component library all inherit this
  abstract base class. It provides basic methods for setting and
  querying about the relationship between the component object and its
  underlying @Gui@ object(s).

  Application programmers should not need to interface any code
  against this class, unless they want to extend the So@Gui@ library
  in entirely new directions. For making new viewer components, for
  instance, other classes further down the inheritance hierarchy would
  be better suited for subclassing.

  Note that the relationship between all So@Gui@Component derived
  classes and @Gui@ widgets is one of "has-A", \e not "is-A" --
  i.e. So@Gui@Component \e contains a @WIDGET@, it doesn't derive from
  or subclass it.
*/

#include <Inventor/@Gui@/So@Gui@.h>
#include <Inventor/@Gui@/So@Gui@Component.h>
#include <Inventor/@Gui@/So@Gui@ComponentP.h>

#include <Inventor/SbPList.h>

/*!
  \fn void So@Gui@Component::initClasses(void)

  This function initializes the type system for all the component
  classes.  It is called indirectly for you when you call
  So@Gui@::init().

  \sa So@Gui@::init(), So@Gui@Device::initClasses()
*/

/*!
  \fn So@Gui@Component::So@Gui@Component(@WIDGET@ const parent, const char * const name, const SbBool embed)

  This is a protected constructor, used only by derived classes.

  The \a parent argument is the parent widget of the component.  If
  you don't supply a parent, the main window (the one given to or
  returned from So@Gui@::init()) is used (and the \a embed argument is
  considered to be \c FALSE).

  The \a name argument is the name of the component. If you don't
  supply one, the name will default to something, depending on the
  inheritance hierarchy.

  The \a embed argument tells whether the component should be embedded
  in the \a parent widget or should create its own shell. This flag is
  only checked if the \a parent widget argument is specified (not
  \c NULL).

  If you create a non-embedded component, the component will create
  its own shell, which will be a top level shell type. If you embed the
  component, the component will create a form widget type widget inside
  the \a parent widget, which you can get the handle of by calling
  So@Gui@Component::getBaseWidget().
*/

/*!
  \fn So@Gui@Component::~So@Gui@Component()

  Destructor.
*/

/*!
  \fn void So@Gui@Component::addVisibilityChangeCallback(So@Gui@ComponentVisibilityCB * const func, void * const user)

  Add a callback which will be called whenever the widget component
  changes visibility status (because of iconification or
  deiconification, for instance).

  \sa removeVisibilityChangeCallback(), isVisible()
*/

/*!
  \fn void So@Gui@Component::removeVisibilityChangeCallback(So@Gui@ComponentVisibilityCB * const func, void * const data)

  Remove one of the callbacks from the list of visibility notification
  callbacks.

  \sa addVisibilityChangeCallback(), isVisible()
*/

/*!
  \fn void So@Gui@Component::setClassName(const char * const name)

  Set class name of component.

  \sa getClassName(), componentClassName()
*/

/*!
  \fn void So@Gui@Component::setBaseWidget(@WIDGET@ widget)

  Set the core widget for this So@Gui@ component. It is important that
  subclasses get this correct, as the widget set here will be the
  widget returned from query methods.

  \sa baseWidget()
*/

/*!
  \fn void So@Gui@Component::show(void)

  This will show the widget, de-iconifying and raising it if
  necessary.

  \sa hide(), isVisible()
*/

/*!
  \fn void So@Gui@Component::hide(void)

  This will hide the widget.

  \sa show(), isVisible()
*/

/*!
  \fn SbBool So@Gui@Component::isVisible(void)

  Returns visibility status on the widget. If any parents of this
  widget or this widget itself is hidden, returns \c FALSE.

  Note that a widget which is just obscured by other windows on the
  desktop is not hidden in this sense, and \c TRUE will be returned.

  \sa show(), hide()
*/

/*!
  \fn @WIDGET@ So@Gui@Component::getWidget(void) const

  Returns a pointer to the component's window system widget.

  \sa getShellWidget(), getParentWidget()
*/

/*!
  \fn @WIDGET@ So@Gui@Component::getBaseWidget(void) const

  An So@Gui@Component may be composed of any number of widgets in
  parent-children relationships in a tree structure with any depth.
  This method will return the root widget in that tree.

  \sa setBaseWidget()
*/

/*!
  \fn SbBool So@Gui@Component::isTopLevelShell(void) const

  Returns \c TRUE if this component is a top level shell, i.e. it has a
  window representation on the desktop.

  \sa getShellWidget()
*/

/*!
  This method returns the shell widget of the component, but only if
  it was created as a top level shell.  \c NULL will be returned for
  embedded components.

  (The top level shell is the desktop window which contains the
  component.)

  To get the top level shell of embedded components, you can use the
  So@Gui@::getShellWidget() method.

  \sa isTopLevelShell(), getWidget()
*/
@WIDGET@
So@Gui@Component::getShellWidget(void) const
{
  @WIDGET@ w = this->getWidget();
  // the below assert disables SoXt, so I've removed it for now
  // 20031001 larsa
  // assert(w == NULL && "widget not built yet!");
  return (this->isTopLevelShell() && w) ? So@Gui@::getShellWidget(w) : NULL;
}

/*!
  \fn @WIDGET@ So@Gui@Component::getParentWidget(void) const

  Returns the widget which is the parent of (i.e. contains) this
  component's base widget.

  \sa getWidget(), baseWidget(), isTopLevelShell()
*/

/*!
  \fn void So@Gui@Component::setTitle(const char * const title)

  Set the window title of this component. The title will appear on the
  window title bar, if the component manages its own window.

  \if SOQT_DOC

  Note that there is one peculiarity to be aware of if you are using
  the non-commercial version of Qt: only window titles with the
  substring "Qt" in them are allowed (!), and attempts to set a window
  title without this substring will simply be ignored.

  \endif

  \sa getTitle(), setIconTitle(), isTopLevelShell()
*/

/*!
  \fn const char * So@Gui@Component::getTitle(void) const

  Returns the window title.

  If a title has been set, that title will be returned.
  If no title has been set, the default title is returned.

  \sa setTitle(), isTopLevelShell()
*/

/*!
  \fn void So@Gui@Component::setIconTitle(const char * const title)

  This method sets the title of the icon representation of the window.

  The title will appear on the window icon, if the component manages
  its own window.

  \sa getIconTitle(), setTitle(), isTopLevelShell()
*/

/*!
  \fn const char * So@Gui@Component::getIconTitle(void) const

  Returns the title the window has when iconified.

  If an icon title has been set, that icon title is returned.  If no
  icon title has been set, the default icon title is returned.

  \sa setIconTitle(), isTopLevelShell()
*/

/*!
  \fn const char * So@Gui@Component::getWidgetName(void) const

  Returns name of the widget.
*/

/*!
  \fn const char * So@Gui@Component::getClassName(void) const

  Returns class name of widget.
*/

/*!
  This method returns the default name of a component widget class.

  It should be overridden by derived non-abstract classes for the
  topmost widget in the component to have a proper name.
*/
const char *
So@Gui@Component::getDefaultWidgetName(void) const
{
  return "So@Gui@Component";
}

/*!
  This method returns the default window caption string of the
  component.

  It should be overridden by derived non-abstract classes so the
  window and pop-up menu will get a proper title.
*/
const char *
So@Gui@Component::getDefaultTitle(void) const
{
  return "@Gui@ Component";
}

/*!
  This method returns the default icon title of the component.

  It should be overridden by derived non-abstract classes so icons
  will get proper titles.
*/
const char *
So@Gui@Component::getDefaultIconTitle(void) const
{
  return "@Gui@ Component";
}

/*!
  \fn void So@Gui@Component::setSize(const SbVec2s size)

  Resize the component widget.

  The method assumes the caller knows what he is doing.

  \sa getSize()
*/

/*!
  \fn SbVec2s So@Gui@Component::getSize(void) const

  Returns the component widget size.

  The size that is returned is a cached size value, not a value
  fetched from the GUI system.

  \sa setSize()
*/

/*!
  \fn void So@Gui@Component::sizeChanged(const SbVec2s & size)

  Called internally from within the So@Gui@ library when the widget
  embedded in a component changes its size, which is usually triggered
  by end-user interaction.

  This method is then invoked to notify the component that the size
  has changed.  It is called from the top and all the way down to the
  bottom, the size being adjusted to take into account extra
  decorations having been added at each level in the component class
  hierarchy.
*/

/*!
  \fn void So@Gui@Component::setWindowCloseCallback(So@Gui@ComponentCB * const func, void * const data)

  Set up a callback function to use when the component gets closed. A
  component must be a top level shell for this to have any effect.

  For top level shells with no close callback set, the window will
  simply be hidden. The typical action to take in the callback would
  be to delete the component.

  \sa isTopLevelShell()
*/

/*!
  \fn SbBool So@Gui@Component::setFullScreen(const SbBool onoff)

  Toggle full screen mode for this component, if possible.

  Returns \c FALSE if operation failed.  This might happen if the
  toolkit doesn't support attempts at making the component cover the
  complete screen or if the component is not a top level window.
*/

/*!
  \fn SbBool So@Gui@Component::isFullScreen(void) const

  Returns whether this widget/component is in full screen mode or not.
*/

/*!
  \fn void So@Gui@Component::setComponentCursor(const So@Gui@Cursor & cursor)

  Sets the cursor for this component.

  Note: not part of the original SGI InventorXt API.
*/

/*!
  \fn void So@Gui@Component::setWidgetCursor(@WIDGET@ w, const So@Gui@Cursor & cursor)

  Set cursor for a native widget in the underlying toolkit.

  Note: not part of the original SGI InventorXt API.
*/

/*!
  \fn void So@Gui@Component::afterRealizeHook(void)

  A function "hook" / callback invoked just after the window for the
  component has been realized.

  Override this if you need specific initialization for your own
  component or viewer class to happen right after it has been made
  visible, but remember to call upwards in the inheritance hierarchy:

  \code
  void
  MyLittleViewer::afterRealizeHook(void)
  {
    <superclass>::afterRealizeHook();
    // [own initialization here]
  }
  \endcode
*/



// *************************************************************************

/*!
  This method should be used by subclasses to register the widgets
  they set up from the underlying native toolkit, so they can be
  "reverse" mapped to the owner component.

  Subclasses failing to register the widgets they use will cause the
  So@Gui@Component::getComponent() method to fail with those widgets.

  \sa unregisterWidget(), getComponent()
*/
void
So@Gui@Component::registerWidget(@WIDGET@ widget)
{
#if SO@GUI@_DEBUG && 0 // debug
  SoDebugError::postInfo("So@Gui@Component::registerWidget",
                         "registering widget %p", widget);
#endif // debug

  // In case widget was already present.
  void * comp;
  if (SoGuiComponentP::widget2compdict->find((uintptr_t)widget, comp)) {
    if (((So@Gui@Component *)comp) != this) {
#if SO@GUI@_DEBUG
      SoDebugError::postWarning("So@Gui@Component::registerWidget",
                                "widget %p already registered on a different "
                                "component", widget);
#endif // SO@GUI@_DEBUG
      SoGuiComponentP::widget2compdict->remove((uintptr_t)widget);
    }
    else {
      return;
    }
  }

  SoGuiComponentP::widget2compdict->enter((uintptr_t)widget, (void *)this);
}

/*!
  Remove a previously registered native toolkit widget from the
  widget-to-component mappings used by
  So@Gui@Component::getComponent().

  \sa registerWidget()
*/
void
So@Gui@Component::unregisterWidget(@WIDGET@ widget)
{
#if SO@GUI@_DEBUG && 0 // debug
  SoDebugError::postInfo("So@Gui@Component::unregisterWidget",
                         "unregistering widget %p", widget);
#endif // debug

  // Ignore return value to allow a widget to be unregistered several
  // times (it doesn't matter, just as it doesn't matter if a widget
  // is registered multiple times).
  (void)SoGuiComponentP::widget2compdict->remove((uintptr_t)widget);
}

/*!
  Finds and returns the So@Gui@Component corresponding to the given
  @WIDGET@, if any. If the widget does not seem to belong to any
  So@Gui@Component, \c NULL will be returned.
*/
So@Gui@Component *
So@Gui@Component::getComponent(@WIDGET@ widget)
{
  void * comp;
  if (!SoGuiComponentP::widget2compdict->find((uintptr_t)widget, comp)) {
    return NULL;
  }
  return (So@Gui@Component *)comp;
}

// *************************************************************************

#ifndef DOXYGEN_SKIP_THIS

// Remaining code is for the SoGuiComponentP "private implementation"
// class.

SbDict * SoGuiComponentP::widget2compdict = NULL;
int SoGuiComponentP::nrofcomponents = 0;

SoGuiComponentP::SoGuiComponentP(So@Gui@Component * publ)
{
  this->pub = publ;

  if (SoGuiComponentP::widget2compdict == NULL) {
    SoGuiComponentP::widget2compdict = new SbDict;
  }
  SoGuiComponentP::nrofcomponents++;
}

SoGuiComponentP::~SoGuiComponentP()
{
  SoGuiComponentP::nrofcomponents--;
  if (SoGuiComponentP::nrofcomponents == 0) {
#if SO@GUI@_DEBUG
    // Check to see if widgets were forgotten (i.e. missing
    // unregisterWidget() calls).
    SbPList keys, values;
    SoGuiComponentP::widget2compdict->makePList(keys, values);
    for (int i=0; i < keys.getLength(); i++) {
      SoDebugError::postWarning("SoGuiComponentP::~SoGuiComponentP",
                                "widget %p not unregistered for component %p",
                                keys[i], values[i]);
    }
#endif // SO@GUI@_DEBUG

    delete SoGuiComponentP::widget2compdict;
    SoGuiComponentP::widget2compdict = NULL;
  }
}

#endif // DOXYGEN_SKIP_THIS

// *************************************************************************