source: trunk/desktop/idl/wpobject.idl

/* ***** BEGIN LICENSE BLOCK *****
* Version: CDDL 1.0/LGPL 2.1
*
* The contents of this file are subject to the COMMON DEVELOPMENT AND
* DISTRIBUTION LICENSE (CDDL) Version 1.0 (the "License"); you may not use
* this file except in compliance with the License. You may obtain a copy of
* the License at http://www.sun.com/cddl/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is "NOM" Netlabs Object Model
*
* The Initial Developer of the Original Code is
* netlabs.org: Chris Wohlgemuth <cinc-ml@netlabs.org>.
* Portions created by the Initial Developer are Copyright (C) 2005-2007
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
* case the provisions of the LGPL are applicable instead of those above. If
* you wish to allow use of your version of this file only under the terms of
* the LGPL, and not to allow others to use your version of this file under
* the terms of the CDDL, indicate your decision by deleting the provisions
* above and replace them with the notice and other provisions required by the
* LGPL. If you do not delete the provisions above, a recipient may use your
* version of this file under the terms of any one of the CDDL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */

#ifndef WPOBJECT_IDL_INCLUDED
#define WPOBJECT_IDL_INCLUDED

#include <nomobj.idl>

/** \file wpobject.idl 
    
*/
NOMCLASSNAME(WPObject);

#include "wpnativetypes.idl"
#include "nomstring.idl"
#include "nommenu.idl"
#include "nommenuitem.idl"
#include "nomwindow.idl"

#ifdef __NOM_IDL_COMPILER__
interface WPFolderWindow;
#else
#ifndef WPFLDRWINDOW_IDL_INCLUDED
native PWPFolderWindow;
#endif
#endif

#ifdef __NOM_IDL_COMPILER__
interface WPFolder;
#else
#ifndef WPFOLDER_IDL_INCLUDED
native PWPFolder;
#endif
#endif

#ifdef __NOM_IDL_COMPILER__
interface WPNoteBook;
#else
#if 1
#ifndef WPNOTEBOOK_IDL_INCLUDED
native PWPNoteBook;
#endif
#else
#include "wpnotebook.idl"
#endif
#endif

NOMMETACLASS(M_WPObject);

/** \interface WPObject

    This is the root of all desktop classes.
 */
interface WPObject : NOMObject
{
#ifdef __NOM_IDL_COMPILER__
  metaclass=M_WPObject;
  filestem=wpobject;
#endif
  NOMCLASSVERSION(1, 0);

  /* Memory allocation */
  /**
     Allocate a block of \e cbBytes length. The storage area
     is tracked in the objects inuse list.

     \par How to override:
     This method is usually not overriden.

     \param cbBytes Number of bytes to allocate.
     \param prc Pointer to a gulong which will hold an error code if the method fails.
     \return A pointer to the block of memory

     \sa wpFreeMem()
   */
  gpointer wpAllocMem(in gulong cbBytes,
                      in pgulong prc);
  /**
     Free a block of memory. The method removes the memory block from the objects inuse
     list. Because NOM uses a garbage collector the memory isn't freed instantly but
     will be collected later.

     \remark It is save to call this method with a NULL memory pointer.

     \par How to override:
     This method is usually not overriden.

     \param pByte Block of memory to be freed. This may be NULL.
     \return TRUE if successful.

     \sa wpAllocMem()
   */
  boolean  wpFreeMem(in gpointer pByte);

  /**
     Method to be overriden by classes when they need to do some setup.

     \remark Desktop classes should override this method instead of nomInit().

     \par How to override:
     This method should be overriden by classes which need initialization. The parent
     must be called first.

     \sa wpUnInitData()
   */
  void     wpInitData();

  /**
     Method to be overriden by classes when they need to do some unititialization work.

     \remark Desktop classes should override this method instead of nomUnInit().

     \par How to override
     This method should be overriden by classes which need uninitialization. The parent must
     be called last.

     \sa wpInitData()
   */
  void     wpUnInitData();

  /**
     This method always opens a new view of an object. The concurrent view setting is not
     taken into account. wpViewObject() should be called most of the time.

     \par How to override:
     Desktop objects override this method when they have a private view.

     \param nomFolder The folder view (window) containing the object. Note that an object may
     live in different folder windows at the same time.
     \param ulView The view to be opened.
     \param nameSpaceId See menu handling for more information.
     \param pParam Reserved and must be set to NULL.
     \return A pointer to the view.

     \sa wpViewObject()
  */
  gpointer wpOpen(in PWPFolderWindow nomFolder, in gulong ulView, in nomId nameSpaceId, in gpointer pParam);

  /**
     Increase the use counter of the object.

     \remark The increment operation on the internal counter is an atomic operation but be aware
     that the method call itself is not.

     \par How to override:
     This method is usually not overriden.

     \sa wpObjectIsLocked(), wpUnlockObject()
   */
  void     wpLockObject();

  /**
     Decrease the use counter of the object.

     \remark When the use counter of an object reaches 0 the object will be destroyed.
     The decrement operation on the internal counter is an atomic operation but be aware
     that the method call itself is not.

     \par How to override:
     This method is usually not overriden.

     \sa wpObjectIsLocked(), wpLockObject()
   */
  boolean  wpUnlockObject();

  /**
     Query if the object is in use.

     \remark This method reflects the state of the object at the time of the call. Note that
     in a multithreaded environment other threads may alter the use counter at any time.

     \par How to override:
     This method is usually not overriden.

     \return TRUE if the objects use counter is greater than 0. This means the object is still in use.

     \sa wpLockObject(), wpUnlockObject()
   */
  boolean  wpObjectIsLocked();
  gpointer wpQueryIcon();

  /**
     Request the object semaphor which protects the objects data structures. For example
     before changing the in use list of the object the semaphor is aquired to prevent
     access from several places at the same time.

     \par How to override
     This method is usually not overriden.

     \return 0 if no error occured. Any other value describes an error.

     \sa wpReleaseObjectMutexSem()
   */
  unsigned long  wpRequestObjectMutexSem(in unsigned long ulReserved);

  /**
     Release the object semaphor which protects the objects data structures. For example
     before changing the in use list of the object the semaphor is aquired to prevent
     access from several places at the same time.

     \par How to override:
     This method is usually not overriden.

     \return 0 if no error occured. Any other value describes an error.

     \sa wpRequestObjectMutexSem()
   */
  unsigned long wpReleaseObjectMutexSem();

  void wpSetTitle(in PNOMString pnomStrNewTitle);
  PNOMString wpQueryTitle();

  PNOMMenu wpDisplayMenu(in PWPFolderWindow nomFolder, in gpointer gReserved, in unsigned long ulMenuType,
                         in unsigned long ulReserved);
  void wpModifyMenu(in PWPFolderWindow nomFolder, in PNOMMenu nomMenu, in unsigned long ulMenuType);
  void wpFilterMenu(in PWPFolderWindow nomFolder, in PNOMMenu nomMenu, in unsigned long ulMenuType,
                    in unsigned long ulFlags);
  boolean wpMenuItemSelected(in PWPFolderWindow nomFolder, in PNOMMenuItem nomMenuItem);
  void wpInsertMenuItem( in PNOMMenu nomMenu, in PNOMMenuItem nomMenuItem, in unsigned long ulPosition);

  /* Settings pages */
  boolean wpAddSettingsPages(in PWPNoteBook wpNoteBook);
  unsigned long wpInsertSettingsPage(in PWPNoteBook wpNoteBook, in gpointer ppageinfo);
  unsigned long wpAddObjectGeneralPage(in PWPNoteBook wpNoteBook);

  /**
     This method either resurfaces an existing view or creates a new view according to the
     objects concurrent view setting.

     If concurrent view is set to \e No the objects inuse list is searched for an existing
     view of the kind being requested. If found the view is brought to the front. If concurrent
     view setting is \e yes or no view can be found wpOpen() is called to create a new view.

     \remark This method should be use in preference to the wpOpen() method.

     \par How to override:
     This method is usually not overriden.

     \param nomFolder The folder view (window) containing the object. Note that an object may
     live in different folder windows at the same time.
     \param ulView The view to be opened.
     \param nameSpaceId See menu handling for more information.
     \param pParam Reserved and must be set to NULL.
     \return A pointer to the view.

     \sa wpOpen(), wpSwitchTo()
   */
  gpointer wpViewObject(in PWPFolderWindow nomFolder, in gulong ulView, in nomId nameSpaceId, in gpointer pParam);

  /**
     Search the objects inuse list for the given view and if found bring it to the front.

     \par How to override:
     This method is usually not overriden.

     \param ulView The view to be opened.
     \param nameSpaceId See menu handling for more information.
     \return A pointer to the view or NULL if no view exists.

     \sa wpViewObject()
   */
  gpointer wpSwitchTo(in gulong ulView, in nomId nameSpaceId);
  boolean wpRegisterView(in PNOMWindow pWindow, in PNOMString nomStrViewTitle);

  /* ---- Inuse list methods ---- */

  /**
     Register an inuse item in the objects inuse list. Inuse items may describe blocks of
     memory used by the object, open views and some more.

     \par How to override:
     This method is usually not overriden.


     \return TRUE if success.

     \sa wpDeleteFromObjUseList(), wpFindUseItem(), wpFindViewItem()
   */
  boolean   wpAddToObjUseList(in PUSEITEM pUseItem);

  /**
     Remove an inuse item from the objects inuse list. Inuse items may describe blocks of
     memory used by the object, open views and some more.

     \remark The use item will not be freed by this method. This must be done by the caller.

     \par How to override:
     This method is usually not overriden.

     \param pUseItem Use item to be removed from the objects inuse list.
     \return TRUE if success.

     \sa wpAddToObjUseList(), wpFindUseItem(), wpFindViewItem()
  */
  boolean   wpDeleteFromObjUseList(in PUSEITEM pUseItem);

  /**
     Find a useitem previously registerd using wpAddToObjUseList(). 

     \param ulType The type of the useitem e.g. USAGE_MEMORY.
     \param pCurrentItem If set to NULL the first item is returned. When set
     to a useitem pointer the next matching useitem is searched.

     \return A pointer to a useitem or NULL if no matchin item can be found.
     
     \sa wpAddToObjUseList(), wpDeleteFromObjUseList(), wpFindViewItem()
   */
  PUSEITEM  wpFindUseItem( in gulong ulType, in PUSEITEM pCurrentUseItem);

  PVIEWITEM wpFindViewItem( in gulong ulView, in nomId nameSpaceId, in PVIEWITEM pCurrentItem);

  boolean wpSaveDeferred();
  boolean wpSaveImmediate();

  /**
     Set the information about the folder this object is living in. This method is called for
     example if the object is moved to another location.

     \par How to override:
     This method is usually not overriden.

     \param wpParentFolder The folder this object is living in.
     \return Folder object. Note that this is not a folder view (window).

     \sa wpQueryFolder()
   */
  void wpSetFolder(in PWPFolder wpParentFolder);

  /**
     Get the folder this object is living in.

     \par How to override:
     This method is usually not overriden.

     \return Folder object. Note that this is not a folder view (window).

     \sa wpSetFolder()
   */
  PWPFolder wpQueryFolder();

  void wpSetTitleFromCString(in string chrNewTitle);

  gulong wpQueryDefaultView(in pnomId pNameSpaceId);
  boolean wpSetDefaultView(in gulong ulView , in nomId nameSpaceId);

  void   wpSetConcurrentView(in gulong ulCCView);
  gulong wpQueryConcurrentView();

  gulong wpDragOver(in gpointer containerHandle, in gpointer pDragInfo);

  gulong wpDrop(in gpointer containerHandle, in gpointer pDragInfo);

  /**
    Move an object to a new location.
    
    \remark This method removes the object from the content list of the
    source folder and inserts it into the list of the target folder using
    wpDeleteFromContent() and wpAddToContent(). The same is done for the stores
    held by the source and target folders.
    Note that this method must be overriden by subclasses to actually perform
    any moving of files. 

    \par How to override:
    This method is overriden by classes which need special processing when
    objects are moved. The parent method must be called last.

    \param wpTargetFolder The new folder into which the object will be moved.
    If this is not a valid object FALSE is returned.

    \return TRUE when success.

    \sa wpCopyObject()
  */
  boolean wpMoveObject(in PWPFolder wpTargetFolder);

  /**
    Copy an object to a new location.
    
    \par How to override:
    This method is overriden by classes which need special processing when
    objects are copied. An override can also be used to keep track of created
    objects.

    \param wpTargetFolder The new folder into which the object will be moved.
    \param fLock If set TRUE the created object will be locked after creation.
    A call to wpUnlockObject() is necessary so the object can go dormant. If
    set to FALSE the object will be made dormant if the object is no longer used
    and the folder containing it is closed.

    \return TRUE when success.

    \sa wpMoveObject()
  */

  PWPObject wpCopyObject(in PWPFolder wpTargetFolder, in boolean fLock);

  /* Methods overriden by this class */

  /**
     Override of nomInit(). The object semaphore for serializing access to 
     objects data is created here. After setting it up wpInitData() is called.
     This method should be overriden by desktop classes instead of nomInit().
   */
  NOMOVERRIDE(nomInit);

  /**
     Override of nomUnInit(). First wpUnitData() is called on the object. Note
     that desktop classes should override wpUnInitData() instead of nomUnInit.

     After destroying the object semaphor nomUnInit() is called.

     \remark This override will put any desktop object on the list of objects with
     finalizers.
   */
  NOMOVERRIDE(nomUnInit);

  /* Instancce variables of this class. Theses are not
     attributes. */
  /**
     Object lock counter instance variable. This variable is private and can't be accessed
     from the outside.

     \sa wpObjectIsLocked(), wpLockObject(), wpUnlockObject()
   */
  NOMINSTANCEVAR(gint iLockCounter);

  /**
     Object semaphor. This variable is private and can't be accessed
     from the outside.

     \sa wpRequestObjectMutexSem(), wpReleaseObjectMutexSem()
   */
  NOMINSTANCEVAR(HMUX gObjectMutex);
  NOMINSTANCEVAR(PGSList glstObjectInUse);
  NOMINSTANCEVAR(PNOMString pnomStringTitle);
  /**
     This instance variable holds the pointer to the folder containing this
     object.

     \remarks This variable may be accessed using wpQueryFolder() and wpSetFolder()

     \sa wpQueryFolder(), wpSetFolder()
   */
  NOMINSTANCEVAR(PWPFolder wpParentFldr);
};

#endif /* WPOBJECT_IDL_INCLUDED */