#ifndef _SHAPEUP_API_H
#define _SHAPEUP_API_H
/** \mainpage ShapeUp API
This is the API for ShapeUp General Plug-Ins, a.k.a. GPI's. The support for
GPI's was introduced in ShapeUp v1.2.00. The main difference between the new GPI
model and the older plug-in types is that it now is the plug-in that defines and
controls what actions to be taken. A GPI can handle all the things the old plug-ins
could do, and a lot more. E.g. hook into ShapeUp menues, create and manage its own
toolbars, draw objects in the map window, utilise the ShapeUp status bar, and a
lot more.
This manual is divided in the following sections:
- \subpage intro
- \subpage hooks "GPI Message Routing"
- \subpage serialization "GPI Serialization"
- \subpage threading "GPI Threading"
*/
//-----------------------------------------------------------
/** \page intro Introduction
A GPI is a win32 DLL with the extension '.gpi'.
Unlike the previous plug-in types (except for statistical plug-ins) a GPI
is loaded on start-up, and remains loaded until ShapeUp terminates.
The GPI needs to export three function in order to be considered valid by ShapeUp:\n
\li \c fnInit(), for initialisation
\li \c fnVersion(), to tell ShapeUp what version of the API the GPI was built with.
\li \c fnGUID(), to identify this plug-in.
and optionally:\n
\li \c fnTerminate(), for any clean-up process.
These functions can be exported by declaring them in a .def file for the
project.\n
Now you can proceed to the \ref hooks "GPI Message Routing".
*/
//-----------------------------------------------------------
/** \page hooks GPI Message Routing
When a GPI is initialised, it may hook into one or more notification functions
supplied by ShapeUp. These can be mouse action in the map window, adding menu
items and toolbars and get notified when the user selects an item, etc.
A callback function is supplied to ShapeUp in fnInit() to set the function
which should be notified on the subscribed events. This is the pfnHook
member of the SUImport supplied in the SUExport argument to the function.
\code
SURESULT __cdecl fnInit(SUExport *pExport)
{
...
pExport->import.pfnHook = MyHookFunc;
...
}\endcode
For the purpose of adding notification hooks, the ShapeUp API exposes several
functions on the form \a ShapeUp_AddXxxHook(), see \ref example_hooks.cpp "example_hooks.cpp".
As an example, study the following:
\code
SURESULT __cdecl fnInit(SUExport *pExport)
{
...
ShapeUp_AddPostDrawHook(0);
...
}\endcode
This will tell ShapeUp to notify the GPI when the map has been refreshed
to allow the plug-in to overlay its own graphics.
A sample of the hook function might look like:
\code
SURESULT __cdecl MyHookFunc(SUHANDLE hWorkspace, int hookType, SUHookData *args)
{
switch (hookType)
{
case HOOKTYPE_POSTDRAW:
DrawSomething();
break;
default:
break;
}
return SURESULT_OK;
}\endcode
Here, the value found in \a args->userData, is the same value used when adding
the hook. Some of the handlers have more information in the \a args data.
Check each \ref HOOKTYPE for what the \a args really points to. It is however
always safe to treat the \a args as a pointer to a \ref SUHookData struct.
Make sure you have first read \ref intro "the introduction".
*/
//-----------------------------------------------------------
/** \page serialization GPI Serialization
A GPI can store data in the ShapeUp workspace file (*.sup) when the
user chooses to save the workspace. Data can be saved on workspace
basis, and/or on theme basis. When such a workspace is later loaded,
the stored data is sent to the plug-in to be parsed and used.
E.g. if a plug-in draws extra data on top of the map, the settings
for how this is drawn can be stored in the workspace file and reused
when that workspace is reopened.
\note A plug-in can set the data to be serialized at almost any time.
The only time it's not permitted is during the loading process.
A sample of how to store data:
\code
{
struct MyData
{
int version;
double precision;
} data;
const char *string_data = "Some data";
// Store data on workspace level
SUWorkspace workspace(hWorkspace);
workspace.SetSerialData(sizeof(MyData), &data);
// Store data on theme level
SUTheme theme(hTheme);
theme.SetSerialData(strlen(string_data) + 1, string_data);
}\endcode
In order to reserialize data stored, a hook funktion needs to be used,
ShapeUp_AddDeserializeHook(), which enables a call to the GPI hook function
when a loading operation occurrs.
A sample of the deserialize hook functionality might look like:
\code
SURESULT __cdecl fnInit(SUExport *pExport)
{
...
// Set hook function
pExport->import.pfnHook = MyHookFunc;
// Set-up our loading hook
ShapeUp_AddDeserializeHook(0);
...
}
SURESULT __cdecl MyHookFunc(SUHANDLE hWorkspace, int hookType, SUHookData *args)
{
switch (hookType)
{
case HOOKTYPE_DESERIALIZE:
{
// args is really a pointer to a SUDeserializeHookData struct
SUDeserializeHookData *data = (SUDeserializeHookData*) args;
// If data->hTheme == NULL we are loading a workspace, otherwise
// we are loading the theme pointed to by data->hTheme
if (data->hTheme == NULL)
LoadWorkspaceData(hWorkspace, data);
else
LoadThemeData(hWorkspace, data);
}
break;
default:
break;
}
return SURESULT_OK;
}\endcode
\warning Do not assume that the workspace \a hWorkspace in the hook function
will point to the workspace containing the currently loading theme. I.e. if
the user is loading themes from a workspace using the Insert | Add Themes from Workspace
command, the \a hWorkspace will point to the active workspace rather than the
workspace that contains the themes to be extracted. In this case, any serialized
workspace based data in the loading workspace file will remain unread.
This means you cannot store data for a theme that is depending on data
stored for its workspace.
\sa ShapeUp_AddDeserializeHook(), FNTYPE_WORKSPACE_SETSERIALDATA,
FNTYPE_THEME_SETSERIALDATA, HOOKTYPE_DESERIALIZE
Make sure you have first read \ref intro "the introduction".
*/
//-----------------------------------------------------------
/** \page threading GPI Threading
A GPI runs in the ShapeUp main thread, but there is support for having
'collector threads' which asks for a synchronised call from ShapeUp when
actions need to be taken. E.g. a collector thread could run and query
an external data source, like GPS equipment, for updates. When an update
occurrs, the GPI asks ShapeUp to get a synchronised call where it will
take action on the event.
A sample thread function:
\code
#define DATAUPDATE1 0
#define DATAUPDATE2 1
void MyThreadFunc()
{
while (continueToRun)
{
if (DataAvailable())
ShapeUp_WantUpdate(DATAUPDATE1);
...
}
}\endcode
You can use different values as user data for the call to ShapeUp_WantUpdate() to
distinguish different tasks.
A sample of the hook function might look like:
\code
SURESULT __cdecl MyHookFunc(SUHANDLE hWorkspace, int hookType, SUHookData *args)
{
// Here we are synchronized with the ShapeUp main thread, and we can call
// any ShapeUp function.
switch (hookType)
{
case HOOKTYPE_WANTUPDATE:
switch (args->userData)
{
case DATAUPDATE1:
ReadData1AndDoSomething();
break;
case DATAUPDATE2:
ReadData2AndDoSomething();
break;
default:
break;
}
break;
default:
break;
}
return SURESULT_OK;
}\endcode
\sa ShapeUp_WantUpdate(), FNTYPE_SHAPEUP_WANTUPDATE, HOOKTYPE_WANTUPDATE
Make sure you have first read \ref intro "the introduction".
*/
#include "shapeobjects.h"
#include
#include
/** \name VERSION
* \anchor VERSION
* The version of this file.
* \sa fnVersion()
*/
/*@{*/
#define SHAPEUP_API_VERSION 100 /**< This should be returned by the function fnVersion() */
/*@}*/
/********************************************************************
* ShapeUp API types
*******************************************************************/
typedef HANDLE SUHANDLE;
typedef HRESULT SURESULT;
typedef struct tagSUHookData
{
unsigned long userData;
} SUHookData;
typedef struct tagSUShapeSelChangeHookData
{
SUHookData hd;
SUHANDLE hTheme;
BOOL bAllowNewGUI;
} SUShapeSelChangeHookData;
typedef struct tagSUPreRemoveThemeHookData
{
SUHookData hd;
SUHANDLE hTheme;
} SUPreRemoveThemeHookData;
typedef struct tagSUPreRemoveShapeHookData
{
SUHookData hd;
SUHANDLE hTheme;
SUHANDLE hShape;
} SUPreRemoveShapeHookData;
typedef struct tagSUMouseHookData
{
SUHookData hd;
long x;
long y;
UINT flags;
unsigned long ulReserved;
} SUMouseHookData;
typedef struct tagSUToolBarButtonHookData
{
SUHookData hd;
UINT nCommandID;
} SUToolBarButtonHookData;
typedef struct tagSUMenuItemHookData
{
SUHookData hd;
SUHANDLE hMenuItem;
} SUMenuItemHookData;
typedef struct tagSUAddMenuItemHookData
{
unsigned long menuItemType;
const char *menuString;
const char *menuDescr;
HICON hReserved;
SUHANDLE *hMenuItem;
} SUAddMenuItemHookData;
typedef struct tagSUFileFormatHandlerHookData
{
SUHookData hd;
const char *filename;
} SUFileFormatHandlerHookData;
typedef struct tagSUAddFileFormatHandlerHookData
{
const char *filterdescription;
const char *pattern;
} SUAddFileFormatHandlerHookData;
typedef struct tagSUDeserializeHookData
{
SUHookData hd; /**< \ref SUHookData header. */
SUHANDLE hTheme; /**< Contains a handle to the currently loading theme. If NULL, workspace data is being loaded. */
size_t byteCount; /**< Size in bytes of the \a bytes buffer. */
const void *bytes; /**< Byte buffer containing the data to be loaded. */
} SUDeserializeHookData;
typedef struct tagSUAddJavaScriptInvokeHookData
{
SUHookData hd; /**< \ref SUHookData header. */
const char **properties; /**< Array of supported properties. Array must end with a NULL pointer. */
const char **methods; /**< Array of supported methods. Array must end with a NULL pointer. */
} SUAddJavaScriptInvokeHookData;
typedef enum tagDataType
{
DT_SUHANDLE = 0,
DT_INT = 1,
DT_STRING = 2,
DT_DOUBLE = 3,
DT_BOOL = 4,
DT_COLOR = 5
} DataType;
typedef struct tagSUJavaScriptArgument
{
DataType type;
union {
SUHANDLE handleVal;
int intVal;
char* stringVal;
double doubleVal;
BOOL boolVal;
COLORREF colorVal;
};
} SUJavaScriptArgument;
/** \name JavaScriptInvokeHookData flags
* \anchor JavaScriptInvokeHookDataFlags
* The JavaScriptInvokeHookData flags are used in the JavaScriptInvokeHookData
* struct.
*/
/*@{*/
/********************************************************************
* JavaScriptInvokeHookData flags
********************************************************************/
/* | Name |Value | Comment */
#define JSIHDF_DEFAULT 0x00000000 /**< Default value. */
#define JSIHDF_TREATRETURNASSINGLEVALUE 0x00000001 /**< Used to indicate that there is only one returned value, and
* that it should not be treated as an Array in JavaScript. */
/*@}*/
/** \example example_javascriptable.cpp
* This is an example on how to enable a GPI for scripting.
*/
/** This is an example of how to construct the return values.
* \code
* // Let's return 2 values, a shape and a string, to the calling JavaScript
* // (Error handling omitted for simplicity)
*
* SUJavaScriptInvokeHookData *args; // From the hook function
* SUHANDLE hWorkspace; // From the hook function
*
* args->retc = 2;
* ShapeUp_Allocate(sizeof(SUJavaScriptArgument) * args->retc, (void**)&args->rets);
*
* args->rets[0].type = DT_SUHANDLE;
* args->rets[0].handleVal = SUWorkspace(hWorkspace).GetTheme(0).GetShape(0);
*
* args->rets[1].type = DT_STRING;
* args->rets[1].stringVal = ShapeUp_DuplicateString("A string");
* \endcode
* The return value is by default treated as an Array of values, even if there
* is only one element. To avoid this if the intention is just to return one
* value, set the \a flags member of SUJavaScriptInvokeHookData to include
* \ref JSIHDF_TREATRETURNASSINGLEVALUE.
*
* The following return values are supported:
* \li int
* \li double
* \li null terminated char*
* \li boolean
* \li COLORREF
* \li \ref SUHANDLE to a theme
* \li \ref SUHANDLE to a shape
*
* \note It's important to use ShapeUp_Allocate() or one of its relatives to allocate
* memory for the return values since ShapeUp will deallocate the structure.
*
* The hook function can return any of:
* \li \ref SURESULT_OK to indicate success.
* \li \ref SURESULT_E_NOTIMPLEMENTED to indicate the the call was not handled.
* \li \ref SURESULT_E_ILLEGALPARAM to indicate that the parameters were incorrect for this method.
*
* \sa ShapeUp_Allocate(), ShapeUp_DuplicateString()
*/
typedef struct tagSUJavaScriptInvokeHookData
{
SUHookData hd; /**< \ref SUHookData header. */
const char* name; /**< Contains the name of the property or method being invoked. */
DWORD flags; /**< See \ref JavaScriptInvokeHookDataFlags for appropriate values. */
size_t argc; /**< Count of the arguments pointed to by \a args. */
const SUJavaScriptArgument *args; /**< Argument array containing the data sent to the plug-in. */
size_t retc; /**< Count of the return values pointed to by \a rets. Filled in by the GPI. */
SUJavaScriptArgument *rets; /**< Return array containing the data sent back to the JavaScript. Filled in by the GPI. */
} SUJavaScriptInvokeHookData;
typedef SURESULT (__cdecl *SUHOOKFUNC)(SUHANDLE hWorkspace, int hookType, SUHookData *args);
typedef void (__cdecl *PFNSETTINGS)();
/** \example example_loadergpi.cpp
* This is an example on how to create a loader plug-in using the new GPI
* object model.
*/
/** \name MENUITEMTYPE
* \anchor MENUITEMTYPE
* The MENUITEMTYPES are indicators to where ShapeUp will add new menu items.
* The SUHOOKFUNC defined in the GPI will receive a notification with args
* being a pointer to a SUMenuItemHookData.
*/
/*@{*/
/********************************************************************
* Menu item types
********************************************************************/
/* | Name |Value | Comment */
#define __MENUITEMTYPE_NIL__ 0x0000 /**< Invalid value. */
#define MENUITEMTYPE_ADDNEWLAYER 0x0001 /**< Used when a new layer can be constructed without an external data source.
* E.g. Use this for layers created from a selection of objects in another theme. */
#define MENUITEMTYPE_LOADLAYER 0x0002 /**< Used when a new layer can be constructed from an external data source. */
#define MENUITEMTYPE_ADVANCEDSELECTION 0x0003 /**< Used to add an item in the Edit | Advanced Selection sub-menu. */
#define MENUITEMTYPE_ADVANCEDEDIT 0x0004 /**< Used to add an item in the Edit | Advanced Edit sub-menu. */
#define MENUITEMTYPE_EXPORTLAYER 0x0005 /**< Used to add an item in the Theme | Export dialog. */
#define MENUITEMTYPE_TOOLS 0x0006 /**< Used to add an item in the Tools menu. */
#define MENUITEMTYPE_COPYSPECIAL 0x0007 /**< Used to add an item in the Edit | Copy Special sub-menu. */
#define __MENUITEMTYPE_COUNT__ 0x0008 /**< Do not use. For internal use only. */
/*@}*/
/** \example example_hooks.cpp
* This is an example of how to use the hooks in a GPI to get
* notifications of ShapeUp events.
*/
/** \name HOOKTYPE
* \anchor HOOKTYPE
* The hook types are used in the GPI hook function, SUHOOKFUNC, set by
* the plug-in in SUImport on start-up.
* \sa fnInit, SUExport, SUImport, SUHOOKFUNC
*/
/*@{*/
/********************************************************************
* Hook types
********************************************************************/
/* | Name |Value | ARG type */
#define __HOOKTYPE_NIL__ 0x0000 /**< Invalid value. */
#define HOOKTYPE_POSTDRAW 0x0001 /**< args is of type \ref SUHookData*. */
#define HOOKTYPE_IDLE 0x0002 /**< args is of type \ref SUHookData*. */
#define HOOKTYPE_MOUSEMOVE 0x0003 /**< args is of type \ref SUMouseHookData*. */
#define HOOKTYPE_SHAPESELCHANGE 0x0004 /**< args is of type \ref SUShapeSelChangeHookData*. */
#define HOOKTYPE_PRECLOSEWORKSPACE 0x0005 /**< args is of type \ref SUHookData*. */
#define HOOKTYPE_PREREMOVETHEME 0x0006 /**< args is of type \ref SUPreRemoveThemeHookData*. */
#define HOOKTYPE_LBUTTONDOWN 0x0007 /**< args is of type \ref SUMouseHookData*. */
#define HOOKTYPE_LBUTTONUP 0x0008 /**< args is of type \ref SUMouseHookData*. */
#define HOOKTYPE_TOOLBARBUTTON 0x0009 /**< args is of type \ref SUToolBarButtonHookData*. */
#define HOOKTYPE_MENUITEM 0x000A /**< args is of type \ref SUMenuItemHookData*. */
#define HOOKTYPE_PREREMOVESHAPE 0x000B /**< args is of type \ref SUPreRemoveShapeHookData*. */
#define HOOKTYPE_WANTUPDATE 0x000C /**< args is of type \ref SUHookData*. */
#define HOOKTYPE_FILEFORMATHANDLER 0x000D /**< args is of type \ref SUFileFormatHandlerHookData*. */
#define HOOKTYPE_DESERIALIZE 0x000E /**< args is of type \ref SUDeserializeHookData*. */
#define HOOKTYPE_WORKSPACEREADY 0x000F /**< args is of type \ref SUHookData*. */
#define HOOKTYPE_JAVASCRIPTINVOKE 0x0010 /**< args is of type \ref SUJavaScriptInvokeHookData*. */
#define HOOKTYPE_LAYERSELCHANGE 0x0011 /**< args is of type \ref SUHookData*. */
#define __HOOKTYPE_COUNT__ 0x0012 /**< Do not use. For internal use only. */
/*@}*/
/** \name MAPSTATE
* \anchor MAPSTATE
* The various MAPSTATE defines are used with functions Map_GetInteractionState()
* and Map_SetInteractionState(). States supplied by a GPI must be in the range
* [\ref MAPSTATE_PLUGINSTATEFIRST, \ref MAPSTATE_PLUGINSTATELAST]
*/
/*@{*/
/********************************************************************
* Map interaction states
********************************************************************/
/* | Name |Value | Comment */
#define __MAPSTATE_NIL__ 0x0000 /**< Invalid value. */
#define MAPSTATE_SINGLESELECT 0x0001 /**< Single select mode enabled. */
#define MAPSTATE_RECTSELECT 0x0002 /**< Rectangle select mode enabled. */
#define MAPSTATE_RECTSELECTTRACKING 0x0003 /**< Rectangle selection in progress. Read-only state. */
#define MAPSTATE_CIRCLESELECT 0x0004 /**< Circle select mode enabled. */
#define MAPSTATE_CIRCLESELECTTRACKING 0x0005 /**< Cirlce selection in progress. Read-only state. */
#define MAPSTATE_PAN 0x0006 /**< Panning mode enabled. */
#define MAPSTATE_PANNING 0x0007 /**< Panning in progress. Read-only state. */
#define MAPSTATE_ZOOMIN 0x0008 /**< Zoom in mode enabled. */
#define MAPSTATE_ZOOMINTRACKING 0x0009 /**< Zomming in progress. Read-only state. */
#define MAPSTATE_ZOOMOUT 0x000A /**< Zoom out mode enabled. */
#define MAPSTATE_MEASURING 0x000B /**< Measuring mode enabled. */
#define MAPSTATE_DRAWING 0x000C /**< Drawing mode enabled. */
#define MAPSTATE_ADJUSTVERTEX 0x000D /**< Adjust vertex mode enabled. */
#define MAPSTATE_ADJUSTINGVERTEX 0x000E /**< Adjusting vertex in progress. Read-only state. */
#define MAPSTATE_ADDVERTEX 0x000F /**< Add new vertex mode enabled. */
#define MAPSTATE_ADDINGVERTEX 0x0010 /**< Adding new vertex in progress. Read-only state. */
#define MAPSTATE_POLYGONSELECT 0x0011 /**< Polygon selection mode enabled. */
#define MAPSTATE_POLYGONSELECTTRACKING 0x0012 /**< Polygon selection in progress. Read-only state. */
#define MAPSTATE_SPLITOBJECT 0x0013 /**< Split object mode enabled. */
#define MAPSTATE_SPLITTINGOBJECT 0x0014 /**< Splitting object in progress. Read-only state. */
#define __MAPSTATE_COUNT__ 0x0015 /**< Do not use. For internal use only. */
#define MAPSTATE_CUSTOM 0x00FF /**< Indicates that another GPI has set a map state. This is a read-only state. */
#define MAPSTATE_PLUGINSTATEFIRST 0x0100 /**< First available custom GPI state */
/* ...range to... */
#define MAPSTATE_PLUGINSTATELAST 0x01FF /**< Last available custom GPI state */
/*@}*/
/** \name ATTRIBUTETYPE
* \anchor ATTRIBUTETYPE
* Attribute types are used to determine the types of the attributes
* in a ShapeUp layer. They are also used when adding new attributes
* to a layer.
*
* Any of the types can be combined with the \ref ATTRIBUTETYPE_PRIMARYKEY
* flag to indicate that the attribute is part of a primary key.
*/
/*@{*/
/********************************************************************
* Attribute types
********************************************************************/
/* | Name |Value | Comment */
#define ATTRIBUTETYPE_STRING 0 /**< String attribute. */
#define ATTRIBUTETYPE_INT 1 /**< Integer attribute. */
#define ATTRIBUTETYPE_DOUBLE 2 /**< Double precision floating point attribute. */
#define ATTRIBUTETYPE_DATE 3 /**< Date attribute. */
#define ATTRIBUTETYPE_BOOL 4 /**< Boolean attribute. */
#define ATTRIBUTETYPE_PRIMARYKEY 0x80000000 /**< Indicates this attribute is part of a primary key. */
/*@}*/
/** \name PENSTYLE
* \anchor PENSTYLE
* Pen styles are used to create visual effects for rendered lines.
*/
/*@{*/
/********************************************************************
* Pen styles
********************************************************************/
/* | Name |Value | Comment */
#define PENSTYLE_SOLID 0 /**< A solid drawn line. */
#define PENSTYLE_DASH 1 /**< A dashed line. */
#define PENSTYLE_DOT 2 /**< A dotted line. */
#define PENSTYLE_DASHDOT 3 /**< A dash/dot line. */
#define PENSTYLE_DASHDOTDOT 4 /**< A das/dot/dot line. */
#define __PENSTYLE_COUNT__ 0x0005 /**< Do not use. For internal use only. */
/*@}*/
/********************************************************************
* Function argument types
********************************************************************/
typedef struct tagSUARGAddHook
{
SUHANDLE hShapeUp;
int hookType;
unsigned long userData;
void *args;
} SUARGAddHook;
typedef struct tagSUARGRemoveHook
{
SUHANDLE hShapeUp;
int hookType;
} SUARGRemoveHook;
typedef struct tagSUARGGetErrorDescription
{
SURESULT errCode;
char *buffer;
size_t *bufferSize;
} SUARGGetErrorDescription;
typedef struct tagSUARGCreateToolBar
{
SUHANDLE hShapeUp;
HINSTANCE hInstResource;
LPCTSTR lpszResourceName;
const char *name;
SUHANDLE *hToolBar;
} SUARGCreateToolBar;
typedef struct tagSUARGGetWorkspace
{
size_t nIndex;
SUHANDLE *hWorkspace;
} SUARGGetWorkspace;
typedef struct tagSUARGSetStatusBarPaneInfo
{
SUHANDLE hStatusPane;
const char *text;
HICON hIcon;
void *pReserved;
} SUARGSetStatusBarPaneInfo;
typedef struct tagSUARGAllocateStatusBarPane
{
size_t width;
SUHANDLE *hStatusPane;
} SUARGAllocateStatusBarPane;
typedef struct tagSUARGGetHandle
{
SUHANDLE hObject;
SUHANDLE *hResult;
} SUARGGetHandle;
typedef struct tagSUARGCreateNewTheme
{
SUHANDLE hWorkspace;
ShapeType type;
const char* pszName;
SUHANDLE *hTheme;
} SUARGCreateNewTheme;
typedef struct tagSUARGCreateNewThemeFromSelection
{
SUHANDLE hWorkspace;
SUHANDLE hSourceTheme;
const char* pszName;
SUHANDLE *hResultTheme;
} SUARGCreateNewThemeFromSelection;
typedef struct tagSUARGGetBounds
{
SUHANDLE hObject;
double *xmin;
double *ymin;
double *xmax;
double *ymax;
} SUARGGetBounds;
typedef struct tagSUARGLog
{
SUHANDLE hWorkspace;
const char *line;
} SUARGLog;
typedef struct tagSUARGBrowseTheme
{
SUHANDLE hWorkspace;
const char* pszTitle;
SUHANDLE *hTheme;
} SUARGBrowseTheme;
typedef struct tagSUARGGetSize
{
SUHANDLE hObject;
size_t *width;
size_t *height;
} SUARGGetSize;
typedef struct tagSUARGGPtoDP
{
SUHANDLE hMap;
double gpx;
double gpy;
int *dpx;
int *dpy;
} SUARGGPtoDP;
typedef struct tagSUARGDPtoGP
{
SUHANDLE hMap;
int dpx;
int dpy;
double *gpx;
double *gpy;
} SUARGDPtoGP;
typedef struct tagSUARGGetHWND
{
SUHANDLE hObject;
HWND *hWnd;
} SUARGGetHWND;
typedef struct tagSUARGRepaint
{
SUHANDLE hMap;
BOOL bFullRedraw;
} SUARGRepaint;
typedef struct tagSUARGDraw
{
SUHANDLE hMap;
HDC hdc;
size_t imageWidth;
size_t imageHeight;
double xCenter;
double yCenter;
double geoWidth;
double geoHeight;
} SUARGDraw;
typedef struct tagSUARGSetPoint
{
SUHANDLE hObject;
double x;
double y;
} SUARGSetPoint;
typedef struct tagSUARGSetDouble
{
SUHANDLE hObject;
double doubleval;
} SUARGSetDouble;
typedef struct tagSUARGZoomToSelection
{
SUHANDLE hMap;
SUHANDLE hTheme;
} SUARGZoomToSelection;
typedef struct tagSUARGZoomToExtent
{
SUHANDLE hMap;
SUHANDLE hTheme;
} SUARGZoomToExtent;
typedef struct tagSUARGAddShape
{
SUHANDLE hTheme;
const CShapeRecord *shapeData;
SUHANDLE *hShape;
} SUARGAddShape;
typedef struct tagSUARGReplaceShapeData
{
SUHANDLE hTheme;
SUHANDLE hShape;
const CShapeRecord *shapeData;
} SUARGReplaceShapeData;
typedef struct tagSUARGDeleteShape
{
SUHANDLE hTheme;
SUHANDLE hShape;
} SUARGDeleteShape;
typedef struct tagSUARGGetBOOL
{
SUHANDLE hObject;
BOOL *boolval;
} SUARGGetBOOL;
typedef struct tagSUARGSetBOOL
{
SUHANDLE hObject;
BOOL boolval;
} SUARGSetBOOL;
typedef struct tagSUARGGetText
{
SUHANDLE hObject;
char *buffer;
size_t *bufferSize;
} SUARGGetText;
typedef struct tagSUARGSetText
{
SUHANDLE hObject;
const char *buffer;
} SUARGSetText;
typedef struct tagSUARGGetTextByIndex
{
SUHANDLE hObject;
size_t index;
char *buffer;
size_t *bufferSize;
} SUARGGetTextByIndex;
typedef struct tagSUARGSetTextByIndex
{
SUHANDLE hObject;
size_t index;
const char *buffer;
} SUARGSetTextByIndex;
typedef struct tagSUARGGetDWORD
{
SUHANDLE hObject;
unsigned long *dwordval;
} SUARGGetDWORD;
typedef struct tagSUARGSetDWORD
{
SUHANDLE hObject;
unsigned long dwordval;
} SUARGSetDWORD;
typedef struct tagSUARGGetInteractionState
{
SUHANDLE hMap;
SUHANDLE hShapeUp;
unsigned long *state;
} SUARGGetInteractionState;
typedef struct tagSUARGSetInteractionState
{
SUHANDLE hMap;
SUHANDLE hShapeUp;
unsigned long state;
} SUARGSetInteractionState;
typedef struct tagSUARGGetUnsigned
{
SUHANDLE hObject;
size_t *unsignedval;
} SUARGGetUnsigned;
typedef struct tagSUARGGetUnsignedByIndex
{
SUHANDLE hObject;
size_t nIndex;
size_t *unsignedval;
} SUARGGetUnsignedByIndex;
typedef struct tagSUARGSetUnsigned
{
SUHANDLE hObject;
size_t unsignedval;
} SUARGSetUnsigned;
typedef struct tagSUARGGetHandleByIndex
{
SUHANDLE hObject;
size_t nIndex;
SUHANDLE *hResult;
} SUARGGetHandleByIndex;
typedef struct tagSUARGGetCoordinate
{
SUHANDLE hShape;
size_t nPart;
size_t nIndex;
double *x;
double *y;
double *z;
} SUARGGetCoordinate;
typedef struct tagSUARGGetClosestPoint
{
SUHANDLE hShape;
double refx;
double refy;
double *closestx;
double *closesty;
} SUARGGetClosestPoint;
typedef struct tagSUARGGetShapeType
{
SUHANDLE hObject;
ShapeType *type;
} SUARGGetShapeType;
typedef struct tagSUARGGetIntersectingShapes
{
SUHANDLE hTheme;
SUHANDLE hShape;
SUHANDLE *hRecordset;
} SUARGGetIntersectingShapes;
typedef struct tagSUARGGetInfoTip
{
SUHANDLE hTheme;
SUHANDLE hShape;
char *buffer;
size_t *bufferSize;
} SUARGGetInfoTip;
typedef struct tagSUARGGetFont
{
SUHANDLE hObject;
LOGFONT *font;
COLORREF *clr;
} SUARGGetFont;
typedef struct tagSUARGGetShapesByQuery
{
SUHANDLE hTheme;
const char *where;
SUHANDLE *hRecordset;
} SUARGGetShapesByQuery;
typedef struct tagSUARGGetShapesInRect
{
SUHANDLE hTheme;
double xmin;
double ymin;
double xmax;
double ymax;
BOOL bPartInRectOk;
SUHANDLE *hRecordset;
} SUARGGetShapesInRect;
typedef struct tagSUARGIsShapeSelected
{
SUHANDLE hShape;
SUHANDLE hTheme;
BOOL *selected;
} SUARGIsShapeSelected;
typedef struct tagSUARGSelectShape
{
SUHANDLE hShape;
SUHANDLE hTheme;
BOOL select;
} SUARGSelectShape;
typedef struct tagSUARGGetAttribute
{
SUHANDLE hShape;
SUHANDLE hTheme;
size_t nCol;
char *buffer;
size_t *bufferSize;
} SUARGGetAttribute;
typedef struct tagSUARGSetAttribute
{
SUHANDLE hShape;
SUHANDLE hTheme;
size_t nCol;
const char *data;
} SUARGSetAttribute;
typedef struct tagSUARGSetAttributes
{
SUHANDLE hShape;
SUHANDLE hTheme;
size_t count;
const char **data;
} SUARGSetAttributes;
typedef struct tagSUARGGetShapeBytes
{
SUHANDLE hShape;
unsigned char *buffer;
size_t *bufferSize;
} SUARGGetShapeBytes;
typedef struct tagSUARGSetButtonBOOL
{
SUHANDLE hToolBar;
SUHANDLE hShapeUp;
UINT nID;
BOOL boolval;
} SUARGSetButtonBOOL;
typedef struct tagSUARGBeginProgress
{
const char *title;
float progress;
SUHANDLE *hProgress;
} SUARGBeginProgress;
typedef struct tagSUARGSetFloat
{
SUHANDLE hObject;
float floatval;
} SUARGSetFloat;
typedef struct tagSUARGAddAttribute
{
SUHANDLE hTheme;
unsigned long type;
const char *name;
const char *defaultval;
size_t *index;
} SUARGAddAttribute;
typedef struct tagSUARGGetAttributeType
{
SUHANDLE hTheme;
size_t index;
unsigned long *type;
} SUARGGetAttributeType;
typedef struct tagSUARGDeleteAttribute
{
SUHANDLE hTheme;
size_t index;
} SUARGDeleteAttribute;
typedef struct tagSUARGJSCallFunction
{
SUHANDLE hJavaScript;
const char *name;
} SUARGJSCallFunction;
typedef struct tagSUARGLoadJavaScript
{
SUHANDLE hWorkspace;
const char *file;
SUHANDLE *hJavaScript;
} SUARGLoadJavaScript;
typedef struct tagSUARGWantUpdate
{
SUHANDLE hShapeUp;
unsigned long ulUserData;
} SUARGWantUpdate;
typedef struct tagSUARGGetColor
{
SUHANDLE hObject;
COLORREF *clr;
} SUARGGetColor;
typedef struct tagSUARGSetColor
{
SUHANDLE hObject;
COLORREF clr;
} SUARGSetColor;
typedef struct tagSUARGBatchAddShape
{
SUHANDLE hShapeUp;
SUHANDLE hTheme;
BOOL index_on;
} SUARGBatchAddShape;
typedef struct tagSUARGRemoveTheme
{
SUHANDLE hWorkspace;
SUHANDLE hTheme;
BOOL *ok;
} SUARGRemoveTheme;
typedef struct tagSUARGSetRasterImage
{
SUHANDLE hTheme;
HBITMAP hbm;
double west;
double south;
double east;
double north;
const char *sourceHint;
} SUARGSetRasterImage;
typedef struct tagSUARGSetSerialData
{
SUHANDLE hShapeUp;
SUHANDLE hObject;
size_t byteCount;
const void *bytes;
} SUARGSetSerialData;
typedef struct tagSUARGAddDataPage
{
SUHANDLE hWorkspace;
const char *name;
HWND *page;
SUHANDLE *hDataPage;
} SUARGAddDataPage;
typedef struct tagSUARGAllocate
{
size_t count;
void **bytes;
} SUARGAllocate;
typedef struct tagSUARGGetAttributeIndex
{
SUHANDLE hTheme;
const char *name;
size_t *index;
} SUARGGetAttributeIndex;
/** \name FNTYPE
* \anchor FNTYPE
* Function specifiers used in calls to SUExport::ShapeUp_Call().
*/
/*@{*/
/********************************************************************
* Function types
********************************************************************/
/* | Name |Value | ARG type */
#define __FNTYPE_NIL__ 0x0000
#define FNTYPE_SHAPEUP_ADDHOOK 0x0001 /* SUARGAddHook* */
#define FNTYPE_SHAPEUP_REMOVEHOOK 0x0002 /* SUARGRemoveHook* */
#define FNTYPE_SHAPEUP_REMOVEALLHOOKS 0x0003 /* SUHANDLE hShapeUp */
#define FNTYPE_SHAPEUP_GETERRORDESCRIPTION 0x0004 /* SUARGGetErrorDescription* */
#define FNTYPE_SHAPEUP_GETWORKSPACECOUNT 0x0005 /* size_t* count */
#define FNTYPE_SHAPEUP_GETWORKSPACE 0x0006 /* SUARGGetWorkspace* */
#define FNTYPE_SHAPEUP_GETACTIVEWORKSPACE 0x0007 /* SUHANDLE* hWorkspace */
#define FNTYPE_SHAPEUP_HASJAVASCRIPTSUPPORT 0x005A /* BOOL* pSupport */
#define FNTYPE_SHAPEUP_WANTUPDATE 0x005B /* SUARGWantUpdate* */
#define FNTYPE_SHAPEUP_ISVALIDHANDLE 0x005C /* SUARGGetBOOL* */
#define FNTYPE_SHAPEUP_ALLOCATE 0x0074 /* SUARGAllocate* */
#define FNTYPE_SHAPEUP_DEALLOCATE 0x0075 /* void* */
#define FNTYPE_SHAPEUP_GETVERSION 0x0076 /* SUARGGetText* */
#define FNTYPE_SHAPEUP_SETSTATUSBARTEXT 0x0069 /* SUARGSetText* */
#define FNTYPE_SHAPEUP_SETSTATUSBARPANEINFO 0x0008 /* SUARGSetStatusBarPaneInfo* */
#define FNTYPE_SHAPEUP_ALLOCATESTATUSBARPANE 0x004A /* SUARGAllocateStatusBarPane* */
#define FNTYPE_SHAPEUP_RELEASESTATUSBARPANE 0x004B /* SUHANDLE hStatusPane */
#define FNTYPE_SHAPEUP_BEGINPROGRESS 0x004F /* SUARGBeginProgress* */
#define FNTYPE_SHAPEUP_SETPROGRESS 0x0050 /* SUARGSetFloat* */
#define FNTYPE_SHAPEUP_ENDPROGRESS 0x0051 /* SUHANDLE* hProgress */
#define FNTYPE_TOOLBAR_CREATE 0x0042 /* SUARGCreateToolbar* */
#define FNTYPE_TOOLBAR_ISVISIBLE 0x0079 /* SUARGGetBOOL* */
#define FNTYPE_TOOLBAR_GETBUTTONCOUNT 0x0043 /* SUARGGetUnsigned* */
#define FNTYPE_TOOLBAR_SETBUTTONENABLED 0x0044 /* SUARGSetButtonBOOL* */
#define FNTYPE_TOOLBAR_SETBUTTONCHECKED 0x0045 /* SUARGSetButtonBOOL* */
#define FNTYPE_MENUITEM_SETENABLED 0x004E /* SUARGSetBOOL* */
#define FNTYPE_WORKSPACE_GETMAPWINDOW 0x0009 /* SUARGGetHandle* */
#define FNTYPE_WORKSPACE_GETTHEMECOUNT 0x000A /* SUARGGetUnsigned* */
#define FNTYPE_WORKSPACE_GETTHEME 0x000B /* SUARGGetHandleByIndex* */
#define FNTYPE_WORKSPACE_GETSELECTEDTHEME 0x0055 /* SUARGGetHandle* */
#define FNTYPE_WORKSPACE_GETSELECTEDTHEMES 0x004D /* SUARGGetHandle* */
#define FNTYPE_WORKSPACE_GETSELECTIONCOUNT 0x0078 /* SUARGGetUnsigned* */
#define FNTYPE_WORKSPACE_CREATENEWTHEME 0x000C /* SUARGCreateNewTheme* */
#define FNTYPE_WORKSPACE_CREATENEWTHEMEFROMSELECTION 0x007E /* SUARGCreateNewThemeFromSelection* */
#define FNTYPE_WORKSPACE_GETBOUNDS 0x000D /* SUARGGetBounds* */
#define FNTYPE_WORKSPACE_LOG 0x000E /* SUARGLog* */
#define FNTYPE_WORKSPACE_ISACTIVE 0x000F /* SUARGGetBOOL* */
#define FNTYPE_WORKSPACE_BROWSETHEME 0x0010 /* SUARGBrowseTheme* */
#define FNTYPE_WORKSPACE_REFRESH 0x0048 /* SUHANDLE hWorkspace */
#define FNTYPE_WORKSPACE_LOADJAVASCRIPT 0x0056 /* SUARGLoadJavaScript* */
#define FNTYPE_WORKSPACE_GETCOMMENT 0x005D /* SUARGGetText* */
#define FNTYPE_WORKSPACE_SETCOMMENT 0x005E /* SUARGSetText* */
#define FNTYPE_WORKSPACE_REMOVETHEME 0x006A /* SUARGRemoveTheme* */
#define FNTYPE_WORKSPACE_SETSERIALDATA 0x006C /* SUARGSetSerialData* */
#define FNTYPE_WORKSPACE_ADDDATAPAGE 0x006E /* SUARGAddDataPage* */
#define FNTYPE_WORKSPACE_CLEARSELECTION 0x0073 /* SUHANDLE hWorkspace */
#define FNTYPE_DATAPAGE_REMOVE 0x006F /* SUHANDLE hDataPage */
#define FNTYPE_DATAPAGE_GETHWND 0x0070 /* SUARGGetHWND* */
#define FNTYPE_JAVASCRIPT_RUN 0x0057 /* SUHANDLE hJavaScript */
#define FNTYPE_JAVASCRIPT_CALLFUNCTION 0x0058 /* SUARGJSCallFunction* */
#define FNTYPE_JAVASCRIPT_CLOSE 0x0059 /* SUHANDLE hJavaScript */
#define FNTYPE_MAP_GETBOUNDS 0x0011 /* SUARGGetBounds* */
#define FNTYPE_MAP_GETVIEWSIZE 0x0012 /* SUARGGetSize* */
#define FNTYPE_MAP_GPTODP 0x0013 /* SUARGGPtoDP* */
#define FNTYPE_MAP_DPTOGP 0x0014 /* SUARGDPtoGP* */
#define FNTYPE_MAP_GETHWND 0x0015 /* SUARGGetHWND* */
#define FNTYPE_MAP_REPAINT 0x0016 /* SUARGRepaint* */
#define FNTYPE_MAP_DRAW 0x0017 /* SUARGDraw* */
#define FNTYPE_MAP_CENTERMAP 0x003A /* SUARGSetPoint* */
#define FNTYPE_MAP_ZOOM 0x003B /* SUARGSetDouble* */
#define FNTYPE_MAP_ZOOMTOSELECTION 0x003C /* SUARGZoomToSelection* */
#define FNTYPE_MAP_ZOOMTOEXTENT 0x003D /* SUARGZoomToExtent* */
#define FNTYPE_MAP_GETINTERACTIONSTATE 0x003E /* SUARGGetInteractionState* */
#define FNTYPE_MAP_SETINTERACTIONSTATE 0x003F /* SUARGSetInteractionState* */
#define FNTYPE_THEME_ADDSHAPE 0x0018 /* SUARGAddShape* */
#define FNTYPE_THEME_BATCHADDSHAPE 0x0063 /* SUARGBatchAddShape* */
#define FNTYPE_THEME_REPLACESHAPEDATA 0x0019 /* SUARGReplaceShapeData* */
#define FNTYPE_THEME_DELETESHAPE 0x001A /* SUARGDeleteShape* */
#define FNTYPE_THEME_ISSELECTED 0x001B /* SUARGGetBOOL* */
#define FNTYPE_THEME_ISREADONLY 0x001C /* SUARGGetBOOL* */
#define FNTYPE_THEME_ISVISIBLE 0x004C /* SUARGGetBOOL* */
#define FNTYPE_THEME_GETNAME 0x001D /* SUARGGetText* */
#define FNTYPE_THEME_SETNAME 0x001E /* SUARGSetText* */
#define FNTYPE_THEME_GETATTRIBUTECOUNT 0x001F /* SUARGGetUnsigned* */
#define FNTYPE_THEME_GETSHAPECOUNT 0x0020 /* SUARGGetUnsigned* */
#define FNTYPE_THEME_GETSHAPE 0x0021 /* SUARGGetHandleByIndex* */
#define FNTYPE_THEME_GETSHAPEFROMINDEX 0x0022 /* SUARGGetHandleByIndex* */
#define FNTYPE_THEME_GETSHAPETYPE 0x0023 /* SUARGGetShapeType* */
#define FNTYPE_THEME_GETBOUNDS 0x0024 /* SUARGGetBounds* */
#define FNTYPE_THEME_RECALCBOUNDS 0x0025 /* SUHANDLE hTheme */
#define FNTYPE_THEME_GETINTERSECTINGSHAPES 0x0026 /* SUARGGetIntersectingShapes* */
#define FNTYPE_THEME_GETSELECTIONCOUNT 0x0027 /* SUARGGetUnsigned* */
#define FNTYPE_THEME_GETSELECTEDSHAPES 0x0028 /* SUARGGetHandle* */
#define FNTYPE_THEME_GETINFOTIP 0x0029 /* SUARGGetInfoTip* */
#define FNTYPE_THEME_GETFONT 0x002A /* SUARGGetFont* */
#define FNTYPE_THEME_GETSHAPESBYQUERY 0x002B /* SUARGGetShapesByQuery* */
#define FNTYPE_THEME_GETSHAPESINRECT 0x0040 /* SUARGGetShapesInRect* */
#define FNTYPE_THEME_GETATTRIBUTENAME 0x0046 /* SUARGGetTextByIndex* */
#define FNTYPE_THEME_GETATTRIBUTEINDEX 0x007D /* SUARGGetAttributeIndex* */
#define FNTYPE_THEME_GETATTRIBUTETYPE 0x0077 /* SUARGGetAttributeType* */
#define FNTYPE_THEME_LOOKUPWORKSPACE 0x0049 /* SUARGGetHandle* */
#define FNTYPE_THEME_GETSELECTEDSHAPESINRECT 0x0052 /* SUARGGetShapesInRect* */
#define FNTYPE_THEME_ADDATTRIBUTE 0x0053 /* SUARGAddAttribute* */
#define FNTYPE_THEME_DELETEATTRIBUTE 0x0054 /* SUARGDeleteAttribute* */
#define FNTYPE_THEME_SETATTRIBUTECOMMENT 0x0083 /* SUARGSetTextByIndex* */
#define FNTYPE_THEME_GETCOMMENT 0x005F /* SUARGGetText* */
#define FNTYPE_THEME_SETCOMMENT 0x0060 /* SUARGSetText* */
#define FNTYPE_THEME_GETPENCOLOR 0x0061 /* SUARGGetColor* */
#define FNTYPE_THEME_SETPENCOLOR 0x0062 /* SUARGSetColor* */
#define FNTYPE_THEME_GETFILLCOLOR 0x0065 /* SUARGGetColor* */
#define FNTYPE_THEME_SETFILLCOLOR 0x0066 /* SUARGSetColor* */
#define FNTYPE_THEME_GETPENWIDTH 0x0067 /* SUARGGetUnsigned* */
#define FNTYPE_THEME_SETPENWIDTH 0x0068 /* SUARGSetUnsigned* */
#define FNTYPE_THEME_GETPENSTYLE 0x0081 /* SUARGGetUnsigned* */
#define FNTYPE_THEME_SETPENSTYLE 0x0082 /* SUARGSetUnsigned* */
#define FNTYPE_THEME_SETRASTERIMAGE 0x006B /* SUARGSetRasterImage* */
#define FNTYPE_THEME_SETSERIALDATA 0x006D /* SUARGSetSerialData* */
#define FNTYPE_THEME_CLEARSELECTION 0x0071 /* SUHANDLE hTheme */
#define FNTYPE_THEME_SELECT 0x0072 /* SUARGSetBOOL* */
#define FNTYPE_THEME_INVERTSELECTION 0x007F /* SUHANDLE hTheme */
#define FNTYPE_SHAPE_ISSELECTED 0x002C /* SUARGIsShapeSelected* */
#define FNTYPE_SHAPE_SELECT 0x002D /* SUARGSelectShape* */
#define FNTYPE_SHAPE_GETSHAPETYPE 0x002E /* SUARGGetShapeType* */
#define FNTYPE_SHAPE_GETBOUNDS 0x002F /* SUARGGetBounds* */
#define FNTYPE_SHAPE_GETPARTCOUNT 0x007A /* SUARGGetUnsigned* */
#define FNTYPE_SHAPE_GETCOORDINATECOUNT 0x007B /* SUARGGetUnsignedByIndex* */
#define FNTYPE_SHAPE_GETCOORDINATE 0x007C /* SUARGGetCoordinate* */
#define FNTYPE_SHAPE_GETCLOSESTPOINT 0x0080 /* SUARGGetClosestPoint* */
#define FNTYPE_SHAPE_GETATTRIBUTE 0x0030 /* SUARGGetAttribute* */
#define FNTYPE_SHAPE_SETATTRIBUTE 0x0047 /* SUARGSetAttribute* */
#define FNTYPE_SHAPE_SETATTRIBUTES 0x0064 /* SUARGSetAttributes* */
#define FNTYPE_SHAPE_GETSHAPEBYTES 0x0031 /* SUARGGetShapeBytes* */
#define FNTYPE_RECORDSET_NEXT 0x0032 /* SUHANDLE hRecordset */
#define FNTYPE_RECORDSET_PREV 0x0033 /* SUHANDLE hRecordset */
#define FNTYPE_RECORDSET_FIRST 0x0034 /* SUHANDLE hRecordset */
#define FNTYPE_RECORDSET_LAST 0x0035 /* SUHANDLE hRecordset */
#define FNTYPE_RECORDSET_GET 0x0036 /* SUARGGetHandle* */
#define FNTYPE_RECORDSET_EOF 0x0037 /* SUARGGetBOOL* */
#define FNTYPE_RECORDSET_BOF 0x0038 /* SUARGGetBOOL* */
#define FNTYPE_RECORDSET_CLOSE 0x0039 /* SUHANDLE hRecordset */
#define FNTYPE_RECORDSET_GETCOUNT 0x0041 /* SUARGGetUnsigned* */
#define __FNTYPE_COUNT__ 0x0084
/*@}*/
typedef struct tagSUImport
{
const char *pszName; /**< A short distinct name of this GPI */
const char *pszDescription; /**< A short one-line description of this plug-in. */
const char *pszInfo; /**< A description of this plug-in, possibly multiple lines.
* License and copyright info should go here. */
const char *pszPluginVersion; /**< Version string for this plug-in. */
SUHOOKFUNC pfnHook; /**< Called upon ShapeUp action. */
PFNSETTINGS pfnSettings; /**< Pointer to a function that will display settings
* for this plug-in. If the plug-in has no settings,
* set this to NULL. */
void* pReserved; /**< Reserved for future use. */
} SUImport;
typedef SURESULT (__cdecl *SUCall)(int function, void *arg);
typedef struct tagSUExport
{
SUHANDLE hShapeUp; /**< This is the handle to ShapeUp itself. It's needed in some function calls. */
SUCall ShapeUp_Call; /**< The function to use when to query and control ShapeUp from a GPI. */
SUImport import; /**< This should be filled in by the plug-in. */
} SUExport;
/** \name SURESULT
*/
/*@{*/
/********************************************************************
* ShapeUp API return values
*******************************************************************/
#define SURESULT_OK 0
#define SURESULT_FALSE 1
#define SURESULT_E_NOTIMPLEMENTED 2
#define SURESULT_E_NOSUCHERROR 3
#define SURESULT_E_INVALIDHANDLE 100
#define SURESULT_E_ILLEGALPARAM 101
#define SURESULT_E_UNSUPPORTEDSHAPETYPE 102
#define SURESULT_E_UNEXPECTEDSHAPETYPE 103
#define SURESULT_E_INDEXOUTOFBOUNDS 104
#define SURESULT_E_PERMISSIONDENIED 105
#define SURESULT_E_BUFFEROVERFLOW 106
#define SURESULT_E_INVALIDQUERY 107
#define SURESULT_E_UNKNOWNHOOKTYPE 108
#define SURESULT_E_OUTOFRESOURCES 109
#define SURESULT_E_SCRIPTERROR 110
/*@}*/
/********************************************************************
* ShapeUp API, Functions exported by the plug-in
*******************************************************************/
/** This is the main plug-in function. This function is called after the
* plug-in was loaded to allow the plug-in to hook up into the ShapeUp
* main executable.
* \param export is a pointer to the ShapeUp API SUExport struct which
* in turn has an \a import member which must be initiallised.
* \sa SUExport, SUImport
*/
SURESULT __cdecl fnInit(const SUExport *export);
/** This function should return the version of the ShapeUp API used when
* building the plug-in. This is the defined value SHAPEUP_API_VERSION.
* The plug-in shuld just return this constant.
* \sa SHAPEUP_API_VERSION
*/
size_t __cdecl fnVersion();
/** Identifies this plug-in.
* E.g. used for plug-in invokation from JavaScript.
* Make sure this function returns a newly generated GUID for this plug-in.
*/
const GUID* __cdecl fnGUID();
/** This function is called by ShapeUp just before the plug-in is unloaded.
* Perform any necessary clean-up here. A plug-in is normally not unloaded
* until ShapeUp terminates, but it might be possible for the user to
* unload plugins manually anytime during a ShapeUp session, and thus,
* clean-up should be taken seriously.
*/
void __cdecl fnTerminate();
/********************************************************************
* ShapeUp API, Main functions
*******************************************************************/
inline SURESULT ShapeUp_AddPostDrawHook(unsigned long userData);
inline SURESULT ShapeUp_AddIdleHook(unsigned long userData);
inline SURESULT ShapeUp_AddMouseMoveHook(unsigned long userData);
inline SURESULT ShapeUp_AddLButtonDownHook(unsigned long userData);
inline SURESULT ShapeUp_AddLButtonUpHook(unsigned long userData);
inline SURESULT ShapeUp_AddToolBarButtonHook(unsigned long userData);
inline SURESULT ShapeUp_AddNewLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddLoadLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddCopySpecialHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddAdvancedSelectionHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddAdvancedEditHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddExportLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddRemoveLayerHook(unsigned long userData);
inline SURESULT ShapeUp_AddRemoveShapeHook(unsigned long userData);
inline SURESULT ShapeUp_AddFileFormatHandlerHook(unsigned long userData, const char *filterdescription, const char *pattern);
inline SURESULT ShapeUp_AddToolsHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem);
inline SURESULT ShapeUp_AddDeserializeHook(unsigned long userData);
inline SURESULT ShapeUp_AddWorkspaceReadyHook(unsigned long userData);
inline SURESULT ShapeUp_AddJavaScriptInvokeHook(unsigned long userData, const char *properties[], const char *methods[]);
inline SURESULT ShapeUp_AddShapeSelectionChangedHook(unsigned long userData);
inline SURESULT ShapeUp_AddLayerSelectionChangedHook(unsigned long userData);
inline SURESULT ShapeUp_RemoveMouseMoveHook();
inline SURESULT ShapeUp_RemoveShapeSelectionChangedHook();
inline SURESULT ShapeUp_RemoveLayerSelectionChangedHook();
inline SURESULT ShapeUp_RemoveAllHooks();
inline SURESULT ShapeUp_WantUpdate(unsigned long userData);
inline SURESULT ShapeUp_IsValidHandle(SUHANDLE handle, BOOL *valid);
inline SURESULT ShapeUp_Allocate(size_t count, void **bytes);
inline SURESULT ShapeUp_Deallocate(void *bytes);
inline char* ShapeUp_DuplicateString(const char* str);
inline SURESULT ShapeUp_GetVersion(char *buffer, size_t *bufferSize);
inline SURESULT ShapeUp_GetWorkspaceCount(size_t *count);
inline SURESULT ShapeUp_GetWorkspace(size_t index, SUHANDLE *hWorkspace);
inline SURESULT ShapeUp_GetActiveWorkspace(SUHANDLE *hWorkspace);
inline SURESULT ShapeUp_HasJavaScriptSupport(BOOL *support);
inline SURESULT ShapeUp_GetErrorDescription(SURESULT errCode, char *buffer, size_t *bufferSize);
inline SURESULT ShapeUp_SetStatusBarText(const char *text);
inline SURESULT ShapeUp_SetStatusBarPaneInfo(SUHANDLE hStatusPane, const char *text, HICON hIcon, void *pReserved);
inline SURESULT ShapeUp_AllocateStatusBarPane(size_t width, SUHANDLE *hStatusPane);
inline SURESULT ShapeUp_ReleaseStatusBarPane(SUHANDLE hStatusPane);
inline SURESULT ShapeUp_BeginProgress(const char *title, float progress, SUHANDLE *hProgress);
inline SURESULT ShapeUp_SetProgress(SUHANDLE hProgress, float progress);
inline SURESULT ShapeUp_EndProgress(SUHANDLE hProgress);
/********************************************************************
* ShapeUp API, MenuItem functions
*******************************************************************/
inline SURESULT MenuItem_SetEnabled(SUHANDLE hMenuItem, BOOL bEnabled);
/********************************************************************
* ShapeUp API, ToolBar functions
*******************************************************************/
inline SURESULT ToolBar_Create(HINSTANCE hInstResource, LPCTSTR lpszResourceName, const char *name, SUHANDLE *hToolbar);
inline SURESULT ToolBar_IsVisible(SUHANDLE hToolbar, BOOL *visible);
inline SURESULT ToolBar_GetButtonCount(SUHANDLE hToolbar, size_t *count);
inline SURESULT ToolBar_SetButtonEnabled(SUHANDLE hToolbar, UINT nID, BOOL bEnabled);
inline SURESULT ToolBar_SetButtonChecked(SUHANDLE hToolbar, UINT nID, BOOL bChecked);
/********************************************************************
* ShapeUp API, JavaScript functions
*******************************************************************/
inline SURESULT JavaScript_Run(SUHANDLE hJavaScript);
inline SURESULT JavaScript_CallFunction(SUHANDLE hJavaScript, const char *name);
inline SURESULT JavaScript_Close(SUHANDLE hJavaScript);
/********************************************************************
* ShapeUp API, Workspace functions
*******************************************************************/
inline SURESULT Workspace_GetMapWindow(SUHANDLE hWorkspace, SUHANDLE *hMap);
inline SURESULT Workspace_GetMapWindow(SUHANDLE hWorkspace, SUHANDLE *hMap);
inline SURESULT Workspace_GetThemeCount(SUHANDLE hWorkspace, size_t *count);
inline SURESULT Workspace_GetTheme(SUHANDLE hWorkspace, size_t nIndex, SUHANDLE *hTheme);
inline SURESULT Workspace_GetSelectedTheme(SUHANDLE hWorkspace, SUHANDLE *hTheme);
inline SURESULT Workspace_GetSelectedThemes(SUHANDLE hWorkspace, SUHANDLE *hRecordset);
inline SURESULT Workspace_GetSelectionCount(SUHANDLE hWorkspace, size_t *count);
inline SURESULT Workspace_CreateNewTheme(SUHANDLE hWorkspace, ShapeType type, const char* name, SUHANDLE *hTheme);
inline SURESULT Workspace_CreateNewThemeFromSelection(SUHANDLE hWorkspace, SUHANDLE hSourceTheme, const char* name, SUHANDLE *hTheme);
inline SURESULT Workspace_GetBounds(SUHANDLE hWorkspace, double *xmin, double *ymin, double *xmax, double *ymax);
inline SURESULT Workspace_Log(SUHANDLE hWorkspace, const char *line);
inline SURESULT Workspace_IsActive(SUHANDLE hWorkspace, BOOL *active);
inline SURESULT Workspace_BrowseTheme(SUHANDLE hWorkspace, const char* title, SUHANDLE *hTheme);
inline SURESULT Workspace_Refresh(SUHANDLE hWorkspace);
inline SURESULT Workspace_LoadJavaScript(SUHANDLE hWorkspace, const char* file, SUHANDLE *hJavaScript);
inline SURESULT Workspace_GetComment(SUHANDLE hWorkspace, char *buffer, size_t *bufferSize);
inline SURESULT Workspace_SetComment(SUHANDLE hWorkspace, const char *buffer);
inline SURESULT Workspace_RemoveTheme(SUHANDLE hWorkspace, SUHANDLE hTheme, BOOL *ok);
inline SURESULT Workspace_SetSerialData(SUHANDLE hWorkspace, size_t byteCount, const void *bytes);
inline SURESULT Workspace_AddDataPage(SUHANDLE hWorkspace, const char *name, HWND *page, SUHANDLE *hDataPage);
inline SURESULT Workspace_ClearSelection(SUHANDLE hWorkspace);
/********************************************************************
* ShapeUp API, Map functions
*******************************************************************/
inline SURESULT Map_GetBounds(SUHANDLE hMap, double *xmin, double *ymin, double *xmax, double *ymax);
inline SURESULT Map_GetViewSize(SUHANDLE hMap, size_t *width, size_t *height);
inline SURESULT Map_GPtoDP(SUHANDLE hMap, double gpx, double gpy, int *dpx, int *dpy);
inline SURESULT Map_DPtoGP(SUHANDLE hMap, int dpx, int dpy, double *gpx, double *gpy);
inline SURESULT Map_GetHWND(SUHANDLE hMap, HWND *hWnd);
inline SURESULT Map_Repaint(SUHANDLE hMap, BOOL bFullRedraw);
inline SURESULT Map_Draw(SUHANDLE hMap, HDC hdc, size_t iw, size_t ih, double x, double y, double gw, double gh);
inline SURESULT Map_CenterMap(SUHANDLE hMap, double x, double y);
inline SURESULT Map_Zoom(SUHANDLE hMap, double factor);
inline SURESULT Map_ZoomToSelection(SUHANDLE hMap, SUHANDLE hTheme);
inline SURESULT Map_ZoomToExtent(SUHANDLE hMap, SUHANDLE hTheme);
inline SURESULT Map_GetInteractionState(SUHANDLE hMap, unsigned long *state);
inline SURESULT Map_SetInteractionState(SUHANDLE hMap, unsigned long state);
/********************************************************************
* ShapeUp API, Theme functions
*******************************************************************/
inline SURESULT Theme_AddShape(SUHANDLE hTheme, const CShapeRecord *shapeData, SUHANDLE *hShape);
inline SURESULT Theme_BatchAddShapeBegin(SUHANDLE hTheme);
inline SURESULT Theme_BatchAddShapeEnd(SUHANDLE hTheme);
inline SURESULT Theme_ReplaceShapeData(SUHANDLE hTheme, SUHANDLE hShape, const CShapeRecord *shapeData);
inline SURESULT Theme_DeleteShape(SUHANDLE hTheme, SUHANDLE hShape);
inline SURESULT Theme_IsSelected(SUHANDLE hTheme, BOOL *selected);
inline SURESULT Theme_IsReadOnly(SUHANDLE hTheme, BOOL *readonly);
inline SURESULT Theme_IsVisible(SUHANDLE hTheme, BOOL *visible);
inline SURESULT Theme_GetName(SUHANDLE hTheme, char *buffer, size_t *bufferSize);
inline SURESULT Theme_SetName(SUHANDLE hTheme, const char *buffer);
inline SURESULT Theme_GetAttributeCount(SUHANDLE hTheme, size_t *count);
inline SURESULT Theme_GetAttributeName(SUHANDLE hTheme, size_t column, char *buffer, size_t *bufferSize);
inline SURESULT Theme_GetAttributeType(SUHANDLE hTheme, size_t column, unsigned long *type);
inline SURESULT Theme_GetAttributeIndex(SUHANDLE hTheme, const char* name, size_t *index);
inline SURESULT Theme_GetShapeCount(SUHANDLE hTheme, size_t *count);
inline SURESULT Theme_GetShape(SUHANDLE hTheme, size_t nIndex, SUHANDLE *hShape);
inline SURESULT Theme_GetShapeFromIndex(SUHANDLE hTheme, size_t nIndex, SUHANDLE *hShape);
inline SURESULT Theme_GetShapeType(SUHANDLE hTheme, ShapeType *type);
inline SURESULT Theme_GetBounds(SUHANDLE hTheme, double *xmin, double *ymin, double *xmax, double *ymax);
inline SURESULT Theme_RecalcBounds(SUHANDLE hTheme);
inline SURESULT Theme_GetIntersectingShapes(SUHANDLE hTheme, SUHANDLE hShape, SUHANDLE *hRecordset);
inline SURESULT Theme_GetShapesInRect(SUHANDLE hTheme, double xmin, double ymin, double xmax, double ymax, BOOL bPartInRectOk, SUHANDLE *hRecordset);
inline SURESULT Theme_GetSelectionCount(SUHANDLE hTheme, size_t *count);
inline SURESULT Theme_GetSelectedShapes(SUHANDLE hTheme, SUHANDLE *hRecordset);
inline SURESULT Theme_GetSelectedShapesInRect(SUHANDLE hTheme, double xmin, double ymin, double xmax, double ymax, BOOL bPartInRectOk, SUHANDLE *hRecordset);
inline SURESULT Theme_GetInfoTip(SUHANDLE hTheme, SUHANDLE hShape, char *buffer, size_t *bufferSize);
inline SURESULT Theme_GetFont(SUHANDLE hTheme, LOGFONT *font, COLORREF *clr);
inline SURESULT Theme_GetShapesByQuery(SUHANDLE hTheme, const char *where, SUHANDLE *hRecordset);
inline SURESULT Theme_LookupWorkspace(SUHANDLE hTheme, SUHANDLE *hWorkspace);
inline SURESULT Theme_AddAttribute(SUHANDLE hTheme, unsigned long type, const char *name, size_t *index);
inline SURESULT Theme_DeleteAttribute(SUHANDLE hTheme, size_t index);
inline SURESULT Theme_SetAttributeComment(SUHANDLE hTheme, size_t index, const char *buffer);
inline SURESULT Theme_GetComment(SUHANDLE hTheme, char *buffer, size_t *bufferSize);
inline SURESULT Theme_SetComment(SUHANDLE hTheme, const char *buffer);
inline SURESULT Theme_GetPenColor(SUHANDLE hTheme, COLORREF *clr);
inline SURESULT Theme_SetPenColor(SUHANDLE hTheme, COLORREF clr);
inline SURESULT Theme_GetFillColor(SUHANDLE hTheme, COLORREF *clr);
inline SURESULT Theme_SetFillColor(SUHANDLE hTheme, COLORREF clr);
inline SURESULT Theme_GetPenWidth(SUHANDLE hTheme, size_t *width);
inline SURESULT Theme_SetPenWidth(SUHANDLE hTheme, size_t width);
inline SURESULT Theme_GetPenStyle(SUHANDLE hTheme, size_t *style);
inline SURESULT Theme_SetPenStyle(SUHANDLE hTheme, size_t style);
inline SURESULT Theme_SetRasterImage(SUHANDLE hTheme, HBITMAP hbm, double west, double south, double east, double north, const char *sourceHint);
inline SURESULT Theme_SetSerialData(SUHANDLE hTheme, size_t byteCount, const void *bytes);
inline SURESULT Theme_ClearSelection(SUHANDLE hTheme);
inline SURESULT Theme_Select(SUHANDLE hTheme, bool select);
inline SURESULT Theme_InvertSelection(SUHANDLE hTheme);
/********************************************************************
* ShapeUp API, Shape functions
*******************************************************************/
inline SURESULT Shape_IsSelected(SUHANDLE hShape, SUHANDLE hTheme, BOOL *selected);
inline SURESULT Shape_Select(SUHANDLE hShape, SUHANDLE hTheme, BOOL select);
inline SURESULT Shape_GetShapeType(SUHANDLE hShape, ShapeType *type);
inline SURESULT Shape_GetBounds(SUHANDLE hShape, double *xmin, double *ymin, double *xmax, double *ymax);
inline SURESULT Shape_GetPartCount(SUHANDLE hShape, size_t *count);
inline SURESULT Shape_GetCoordinateCount(SUHANDLE hShape, size_t part, size_t *count);
inline SURESULT Shape_GetCoordinate(SUHANDLE hShape, size_t part, size_t coordIndex, double *x, double *y, double *z);
inline SURESULT Shape_GetClosestPoint(SUHANDLE hShape, double refx, double refy, double *closestx, double *closesty);
inline SURESULT Shape_GetAttribute(SUHANDLE hShape, SUHANDLE hTheme, size_t column, char *buffer, size_t *bufferSize);
inline SURESULT Shape_SetAttribute(SUHANDLE hShape, SUHANDLE hTheme, size_t column, const char *data);
inline SURESULT Shape_GetShapeBytes(SUHANDLE hShape, unsigned char *buffer, size_t *bufferSize);
/********************************************************************
* ShapeUp API, Recordset functions
*******************************************************************/
inline SURESULT Recordset_Next(SUHANDLE hRecordset);
inline SURESULT Recordset_Prev(SUHANDLE hRecordset);
inline SURESULT Recordset_First(SUHANDLE hRecordset);
inline SURESULT Recordset_Last(SUHANDLE hRecordset);
inline SURESULT Recordset_Get(SUHANDLE hRecordset, SUHANDLE *handle);
inline SURESULT Recordset_Eof(SUHANDLE hRecordset, BOOL *eof);
inline SURESULT Recordset_Bof(SUHANDLE hRecordset, BOOL *bof);
inline SURESULT Recordset_Close(SUHANDLE hRecordset);
#ifndef SUAPI_NO_IMPLEMENTATION
extern SUExport suapi;
/********************************************************************
* ShapeUp API, Main functions
*******************************************************************/
/** Helper function for internal use.
* \param ht is the \ref HOOKTYPE value.
* \param ud is the user data.
* \param args is a pointer to the hook specific data.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAddHook, FNTYPE_SHAPEUP_ADDHOOK
*/
inline SURESULT ShapeUp_AddSimpleHook_Helper(int ht, unsigned long ud, void *args)
{
SUARGAddHook addhook;
addhook.hShapeUp = suapi.hShapeUp;
addhook.hookType = ht;
addhook.userData = ud;
addhook.args = args;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_ADDHOOK, &addhook);
}
/** Adds a hook for notifications when ShapeUp has drawn the map.
* This can be used to let the plug-in overlay its own graphics.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_POSTDRAW, \ref SUHookData
*/
inline SURESULT ShapeUp_AddPostDrawHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_POSTDRAW, userData, NULL);
}
/** Adds a hook for notifications when ShapeUp is idle.
* This can be used to let the plug-in update its menu items or
* toolbar buttons states.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_IDLE, \ref SUHookData
*/
inline SURESULT ShapeUp_AddIdleHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_IDLE, userData, NULL);
}
/** Adds a hook for notifications when the mouse is moved within the ShapeUp map.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MOUSEMOVE, \ref SUMouseHookData
*/
inline SURESULT ShapeUp_AddMouseMoveHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MOUSEMOVE, userData, NULL);
}
/** Adds a hook for notifications when the left mouse button is pressed within
* the ShapeUp map.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_LBUTTONDOWN, \ref SUMouseHookData
*/
inline SURESULT ShapeUp_AddLButtonDownHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_LBUTTONDOWN, userData, NULL);
}
/** Adds a hook for notifications when the left mouse button is released within
* the ShapeUp map.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_LBUTTONUP, \ref SUMouseHookData
*/
inline SURESULT ShapeUp_AddLButtonUpHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_LBUTTONUP, userData, NULL);
}
/** Adds a hook for notifications when the user selects one of the plug-ins
* toolbar buttons.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_LBUTTONUP, \ref SUToolBarButtonHookData
*/
inline SURESULT ShapeUp_AddToolBarButtonHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_TOOLBARBUTTON, userData, NULL);
}
/** Adds a menu item in the Insert | New Theme sub-menu. This hook should
* be used if the plug-in creates a new layer not using external data
* sources.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_ADDNEWLAYER, \ref SUMenuItemHookData,
* ShapeUp_AddLoadLayerHook(), HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddNewLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_ADDNEWLAYER;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds a menu item in the Insert | Add Theme From sub-menu. This hook should
* be used if the plug-in creates a new layer using external data
* sources. This is equivalent to the old ShapeUp loader plug-ins.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_LOADLAYER, \ref SUMenuItemHookData,
* ShapeUp_AddNewLayerHook(), HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddLoadLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_LOADLAYER;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds a menu item in the Edit | Copy Special sub-menu. This hook should
* be used if the plug-in can copy objects in a special format and place
* the content on the Clipboard.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_COPYSPECIAL, \ref SUMenuItemHookData,
* HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddCopySpecialHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_COPYSPECIAL;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds a menu item in the Edit | Advanced Selection sub-menu. This hook should
* be used if the plug-in can be used to select objects.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_ADVANCEDSELECTION, \ref SUMenuItemHookData,
* HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddAdvancedSelectionHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_ADVANCEDSELECTION;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds a menu item in the Edit | Advanced Edit sub-menu. This hook should
* be used if the plug-in can be used to edit object data.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_ADVANCEDEDIT, \ref SUMenuItemHookData,
* HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddAdvancedEditHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_ADVANCEDEDIT;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds an item in the Theme | Export dialog. This hook should
* be used if the plug-in can be used to export object data.\n
* Even though the export options are not in a menu directly,
* the added hook can be handled from the plug-in as if it was
* a menu item. If the menu item is set disabled, it will not
* end up in the exporter list. This should be used if the current
* selection is not exportable by the plug-in.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_ADVANCEDEDIT, \ref SUMenuItemHookData,
* HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddExportLayerHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_EXPORTLAYER;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** Adds a hook for notifications when a theme is about to be removed.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_PREREMOVETHEME, \ref SUPreRemoveThemeHookData
*/
inline SURESULT ShapeUp_AddRemoveLayerHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_PREREMOVETHEME, userData, NULL);
}
/** Adds a hook for notifications when a shape is about to be removed.
* If an entire theme is removed, there will not be individual
* notifications for each shape.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_PREREMOVESHAPE, \ref SUPreRemoveShapeHookData
*/
inline SURESULT ShapeUp_AddRemoveShapeHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_PREREMOVESHAPE, userData, NULL);
}
/** Extends the ShapeUp File Open dialog with new file fomats. This hook can
* be used if the plug-in acts as a loader for data stored on file.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param filterdescription is the text that will be displayed in the file
* dialog file type combo box, e.g "Text files (*.txt)".
* \param pattern is the pattern for files that can be handeled, e.g
* "*.txt", or multiple filters separated by ';', e.g "*.txt;*.log".
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_FILEFORMATHANDLER, \ref SUAddFileFormatHandlerHookData,
* ShapeUp_AddLoadLayerHook()
*/
inline SURESULT ShapeUp_AddFileFormatHandlerHook(unsigned long userData, const char *filterdescription, const char *pattern)
{
SUAddFileFormatHandlerHookData hook;
hook.filterdescription = filterdescription;
hook.pattern = pattern;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_FILEFORMATHANDLER, userData, &hook);
return res;
}
/** Adds a menu item in the Tools menu.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param menuString is the text that will be displayed in the menu.
* \param menuDescr is a one-line text describing what the menu item does.
* \param pReserved is not used, and must be set to NULL.
* \param hMenuItem is a pointer to a SUHANDLE that will receive a handle
* to the added menu item. This parameter might be set to NULL if the
* plug-in has no interest in changing its state (enable/disable/...).
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MENUITEM, MENUITEMTYPE_TOOLS, \ref SUMenuItemHookData,
* HOOKTYPE_IDLE
*/
inline SURESULT ShapeUp_AddToolsHook(unsigned long userData, const char *menuString, const char *menuDescr, void *pReserved, SUHANDLE *hMenuItem)
{
SUAddMenuItemHookData anlhook;
anlhook.menuItemType = MENUITEMTYPE_TOOLS;
anlhook.menuString = menuString;
anlhook.menuDescr = menuDescr;
anlhook.hReserved = NULL;
anlhook.hMenuItem = hMenuItem;
SURESULT res = ShapeUp_AddSimpleHook_Helper(HOOKTYPE_MENUITEM, userData, &anlhook);
return res;
}
/** This hook ensures the plugin gets called when a ShapeUp workspace file
* is loaded, if the file contains data that were previously stored by
* this plug-in. If that is the case, the hook funktion will be called
* for the workspace or individual themes within it where applicable.\n
* The hTheme SUHANDLE of the SUDeserializeHookData will be NULL if the
* workspace is deserialized, and contain a valid theme SUHANDLE if a
* theme is deserialized.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_DESERIALIZE, SUDeserializeHookData, Workspace_SetSerialData(),
* Theme_SetSerialData()
*/
inline SURESULT ShapeUp_AddDeserializeHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_DESERIALIZE, userData, NULL);
}
/** This hook is called when a new workspace is created, after any serialization
* has taken place, or after a new empty workspace has been created.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_WORKSPACEREADY, SUHookData
*/
inline SURESULT ShapeUp_AddWorkspaceReadyHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_WORKSPACEREADY, userData, NULL);
}
/** This hook is called when a JavaScript is invoking the plug-in.
* It supports multiple arguments as well as multiple return values
* to and from the plug-in.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \param properties is an array of strings containing property names
* exposed by this GPI. The last element in this array must be NULL.
* If no properties are exposed, this parameter may be set to NULL.
* \param methods is an array of strings containing method names
* exposed by this GPI. The last element in this array must be NULL.
* If no methods are exposed, this parameter may be set to NULL.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_JAVASCRIPTINVOKE, SUHookData
*/
inline SURESULT ShapeUp_AddJavaScriptInvokeHook(unsigned long userData, const char *properties[], const char *methods[])
{
SUAddJavaScriptInvokeHookData h;
h.properties = properties;
h.methods = methods;
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_JAVASCRIPTINVOKE, userData, &h);
}
/** This hook is called when the shape selection changes.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_SHAPESELCHANGE, SUHookData
*/
inline SURESULT ShapeUp_AddShapeSelectionChangedHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_SHAPESELCHANGE, userData, NULL);
}
/** This hook is called when the layer selection changes.
* \param userData is a user specific value that will be sent to
* the hook function when the event occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_LAYERSELCHANGE, SUHookData
*/
inline SURESULT ShapeUp_AddLayerSelectionChangedHook(unsigned long userData)
{
return ShapeUp_AddSimpleHook_Helper(HOOKTYPE_LAYERSELCHANGE, userData, NULL);
}
/** Helper function for internal use.
* \param hookType is the \ref HOOKTYPE value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGRemoveHook, FNTYPE_SHAPEUP_REMOVEHOOK
*/
inline SURESULT ShapeUp_RemoveHook_Helper(int hookType)
{
SUARGRemoveHook h;
h.hookType = hookType;
h.hShapeUp = suapi.hShapeUp;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_REMOVEHOOK, &h);
}
/** Removes the mouse move notification hook set by an earlier call to
* ShapeUp_AddMouseMoveHook().
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_MOUSEMOVE, FNTYPE_SHAPEUP_REMOVEHOOK
*/
inline SURESULT ShapeUp_RemoveMouseMoveHook()
{
return ShapeUp_RemoveHook_Helper(HOOKTYPE_MOUSEMOVE);
}
/** Removes the notification hook set by an earlier call to
* ShapeUp_AddLayerSelectionChangedHook().
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_LAYERSELCHANGE, FNTYPE_SHAPEUP_REMOVEHOOK
*/
inline SURESULT ShapeUp_RemoveLayerSelectionChangedHook()
{
return ShapeUp_RemoveHook_Helper(HOOKTYPE_LAYERSELCHANGE);
}
/** Removes the notification hook set by an earlier call to
* ShapeUp_AddShapeSelectionChangedHook().
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa HOOKTYPE_SHAPESELCHANGE, FNTYPE_SHAPEUP_REMOVEHOOK
*/
inline SURESULT ShapeUp_RemoveShapeSelectionChangedHook()
{
return ShapeUp_RemoveHook_Helper(HOOKTYPE_SHAPESELCHANGE);
}
/** Removes all removable hooks. Not all hooks are removable. Don't use.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_SHAPEUP_REMOVEHOOK
*/
inline SURESULT ShapeUp_RemoveAllHooks()
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_REMOVEALLHOOKS, suapi.hShapeUp);
}
/** Requests a synchronised call from ShapeUp.\n\n If a plug-in is
* running a separate thread, that thread is not allowed to call
* any of the ShapeUp API functions except ShapeUp_WantUpdate().
* The plug-in then has to wait for its hook function to get
* called in which it may access all ShapeUp API functions.
* \param userData is a user specific value that will be sent to
* the hook function when the syncronised call occurs.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGWantUpdate, FNTYPE_SHAPEUP_WANTUPDATE, HOOKTYPE_WANTUPDATE,
* \ref threading "GPI Threading"
*/
inline SURESULT ShapeUp_WantUpdate(unsigned long userData)
{
SUARGWantUpdate arg;
arg.hShapeUp = suapi.hShapeUp;
arg.ulUserData = userData;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_WANTUPDATE, &arg);
}
/** Asks ShapeUp if the supplied handle is a valid one.
* \param handle is the handle to test.
* \param valid is a pointer to a BOOL that will receive the value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_SHAPEUP_ISVALIDHANDLE
*/
inline SURESULT ShapeUp_IsValidHandle(SUHANDLE handle, BOOL *valid)
{
SUARGGetBOOL arg;
arg.hObject = handle;
arg.boolval = valid;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_ISVALIDHANDLE, &arg);
}
/** Allocates a memory buffer. This function should be used where a
* data buffer is handed over from the plug-in to ShapeUp.
* \param count is the number of bytes to allocate.
* \param bytes is the address of a pointer that will receive the
* allocated buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAllocate, FNTYPE_SHAPEUP_ALLOCATE
*/
inline SURESULT ShapeUp_Allocate(size_t count, void **bytes)
{
SUARGAllocate arg;
arg.count = count;
arg.bytes = bytes;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_ALLOCATE, &arg);
}
/** Dellocates a memory buffer previously allocated by ShapeUp_Allocate().
* \param bytes is the buffer to release.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_Allocate(), FNTYPE_SHAPEUP_DEALLOCATE
*/
inline SURESULT ShapeUp_Deallocate(void *bytes)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_DEALLOCATE, bytes);
}
/** Allocates a memory buffer using ShapeUp_Allocate(), and copies
* a given string to it. A string created with this function needs
* to be deallocated by a call to ShapeUp_Deallocate(), or it should
* be sent into one of the ShapeUp API functions that explicitly
* sais it will clean-up the string.
* \param str is the string to duplicate.
* \return This function returns the duplicated string if successful,
* or NULL otherwise.
* \sa ShapeUp_Allocate, ShapeUp_Deallocate
*/
inline char* ShapeUp_DuplicateString(const char* str)
{
size_t count = strlen(str);
char *newstr = NULL;
if (SURESULT_OK == ShapeUp_Allocate(count + 1, (void**)&newstr))
{
strcpy(newstr, str);
return newstr;
}
return NULL;
}
/** Returns the current version of ShapeUp as a string. This is the same string
* as can be seen in the Help | About dialog.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the version string, then the actual text can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_SHAPEUP_GETVERSION
*/
inline SURESULT ShapeUp_GetVersion(char *buffer, size_t *bufferSize)
{
SUARGGetText arg;
arg.hObject = suapi.hShapeUp;
arg.bufferSize = bufferSize;
arg.buffer = buffer;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_GETVERSION, &arg);
}
/** Asks ShapeUp for the number of workspaces currently opened.
* \param count is a pointer to a size_t that will receive the count value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_SHAPEUP_GETWORKSPACECOUNT
*/
inline SURESULT ShapeUp_GetWorkspaceCount(size_t *count)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_GETWORKSPACECOUNT, count);
}
/** Asks ShapeUp for a specific workspace by index.
* \param index is a pointer to a size_t that will receive the count value.
* \param hWorkspace is a pointer to a SUHANDLE that will receive a handle
* to the workspace.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetWorkspace, FNTYPE_SHAPEUP_GETWORKSPACE
*/
inline SURESULT ShapeUp_GetWorkspace(size_t index, SUHANDLE *hWorkspace)
{
SUARGGetWorkspace arg;
arg.nIndex = index;
arg.hWorkspace = hWorkspace;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_GETWORKSPACE, &arg);
}
/** Asks ShapeUp for the workspace currently active.
* \param hWorkspace is a pointer to a SUHANDLE that will receive a handle
* to the workspace.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_SHAPEUP_GETACTIVEWORKSPACE
*/
inline SURESULT ShapeUp_GetActiveWorkspace(SUHANDLE *hWorkspace)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_GETACTIVEWORKSPACE, hWorkspace);
}
/** Asks ShapeUp if it has JavaScript support, i.e. if the Mozilla
* SpiderMonkey js32.dll is present.
* \param support is a pointer to a BOOL that will receive the value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_SHAPEUP_HASJAVASCRIPTSUPPORT
*/
inline SURESULT ShapeUp_HasJavaScriptSupport(BOOL *support)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_HASJAVASCRIPTSUPPORT, support);
}
/** Translates a \ref SURESULT value into a human readable string.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the message, then the actual message can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param errCode is the \ref SURESULT value to translate.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetErrorDescription, FNTYPE_SHAPEUP_GETERRORDESCRIPTION
*/
inline SURESULT ShapeUp_GetErrorDescription(SURESULT errCode, char *buffer, size_t *bufferSize)
{
SUARGGetErrorDescription arg;
arg.errCode = errCode;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_GETERRORDESCRIPTION, &arg);
}
/** Sets informational text in the ShapeUp status bar.
* \param text is a pointer to a null terminated string to be displayed.
* May be NULL to clear the current text.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetText, FNTYPE_SHAPEUP_SETSTATUSBARTEXT
*/
inline SURESULT ShapeUp_SetStatusBarText(const char *text)
{
SUARGSetText arg;
arg.hObject = suapi.hShapeUp;
arg.buffer = text;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_SETSTATUSBARTEXT, &arg);
}
/** Sets information in an allocated pane in the ShapeUp status bar.
* \param hStatusPane is a handle to the status bar pane.
* \param text is a pointer to a null terminated string to be displayed.
* May be NULL to clear the current text.
* \param hIcon is a handle to an icon to be displayed.
* May be NULL to clear the current icon.
* \param pReserved is fur future use, must be NULL.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetStatusBarPaneInfo, ShapeUp_AllocateStatusBarPane(),
* FNTYPE_SHAPEUP_SETSTATUSBARPANEINFO
*/
inline SURESULT ShapeUp_SetStatusBarPaneInfo(SUHANDLE hStatusPane, const char *text, HICON hIcon, void *pReserved)
{
SUARGSetStatusBarPaneInfo arg;
arg.hStatusPane = hStatusPane;
arg.text = text;
arg.hIcon = hIcon;
arg.pReserved = pReserved;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_SETSTATUSBARPANEINFO, &arg);
}
/** Allocates a pane in the ShapeUp status bar. The ShapeUp status bar is
* a limited resource. Use sparingly. When an allocated pane is not needed
* anymore, it should be released with a call to ShapeUp_ReleaseStatusBarPane().
* \param width is the requested width in device units of the new pane.
* \param hStatusPane is a pointer to a \ref SUHANDLE that will receive the pane handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAllocateStatusBarPane, ShapeUp_SetStatusBarPaneInfo(),
* ShapeUp_ReleaseStatusBarPane(), FNTYPE_SHAPEUP_SETSTATUSBARPANEINFO
*/
inline SURESULT ShapeUp_AllocateStatusBarPane(size_t width, SUHANDLE *hStatusPane)
{
SUARGAllocateStatusBarPane arg;
arg.width = width;
arg.hStatusPane = hStatusPane;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_ALLOCATESTATUSBARPANE, &arg);
}
/** Releases a pane in the ShapeUp status bar previously allocated by a call
* to ShapeUp_AllocateStatusBarPane(). A call to this function invalidates
* the \a hStatusPane handle.
* \param hStatusPane is a \ref SUHANDLE to the pane to release.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_AllocateStatusBarPane(), FNTYPE_SHAPEUP_SETSTATUSBARPANEINFO
*/
inline SURESULT ShapeUp_ReleaseStatusBarPane(SUHANDLE hStatusPane)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_RELEASESTATUSBARPANE, hStatusPane);
}
/** Initiates a ShapeUp progress bar session. The ShapeUp progress bar
* is shown in the left corner of the ShapeUp status bar, and can
* be used to show the progress of lengthy operations. When the
* progress bar is not used anymore, it must be released with a call
* to ShapeUp_EndProgress().
* \param title is a null terminated string of text to be displayed to
* the left of the progress bar. May be NULL to show no text.
* \param progress is the initial value of the progress. Usually 0.
* \param hProgress is a pointer to an \ref SUHANDLE that will
* receive the progress bar handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGBeginProgress, ShapeUp_EndProgress(), ShapeUp_SetProgress(),
* FNTYPE_SHAPEUP_BEGINPROGRESS
*/
inline SURESULT ShapeUp_BeginProgress(const char *title, float progress, SUHANDLE *hProgress)
{
SUARGBeginProgress arg;
arg.title = title;
arg.progress = progress;
arg.hProgress = hProgress;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_BEGINPROGRESS, &arg);
}
/** Sets the progress of the ShapeUp progress bar.
* \param hProgress is the \ref SUHANDLE to the progress bar.
* \param progress is the value of the progress. 0 <= \a progress <= 1.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetFloat, ShapeUp_BeginProgress(), FNTYPE_SHAPEUP_SETPROGRESS
*/
inline SURESULT ShapeUp_SetProgress(SUHANDLE hProgress, float progress)
{
SUARGSetFloat arg;
arg.hObject = hProgress;
arg.floatval = progress;
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_SETPROGRESS, &arg);
}
/** Releases the ShapeUp progress bar previously allocated with a call
* to ShapeUp_BeginProgress(). A call to this function invalidates
* the \a hProgress handle.
* \param hProgress is the \ref SUHANDLE to the progress bar.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_BeginProgress(), FNTYPE_SHAPEUP_ENDPROGRESS
*/
inline SURESULT ShapeUp_EndProgress(SUHANDLE hProgress)
{
return suapi.ShapeUp_Call(FNTYPE_SHAPEUP_ENDPROGRESS, hProgress);
}
/********************************************************************
* ShapeUp API, MenuItem functions implementations
*******************************************************************/
/** Enables or disables a ShapeUp menu item.
* \param hMenuItem is the \ref SUHANDLE to the menu item to change.
* \param bEnabled is the new enabled state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetBOOL, FNTYPE_MENUITEM_SETENABLED
*/
inline SURESULT MenuItem_SetEnabled(SUHANDLE hMenuItem, BOOL bEnabled)
{
SUARGSetBOOL arg;
arg.hObject = hMenuItem;
arg.boolval = bEnabled;
return suapi.ShapeUp_Call(FNTYPE_MENUITEM_SETENABLED, &arg);
}
/********************************************************************
* ShapeUp API, ToolBar functions implementations
*******************************************************************/
/** Creates a new ShapeUp toolbar.
* \param hInstResource is plug-in (DLL) resource instance from where
* ShapeUp loads te toolbar resource.
* \param lpszResourceName is resource identifier of the toolbar to load.
* \param name is a null terminated string containing the name of the
* new toolbar. E.g. this name is used in the View | Plug-in Toolbars
* and should be on the form " Toolbar".
* \param hToolbar is a pointer to an \ref SUHANDLE that will
* receive the toolbar handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGCreateToolBar, FNTYPE_TOOLBAR_CREATE
*/
inline SURESULT ToolBar_Create(HINSTANCE hInstResource, LPCTSTR lpszResourceName, const char *name, SUHANDLE *hToolbar)
{
SUARGCreateToolBar arg;
arg.hShapeUp = suapi.hShapeUp;
arg.hInstResource = hInstResource;
arg.lpszResourceName = lpszResourceName;
arg.name = name;
arg.hToolBar = hToolbar;
return suapi.ShapeUp_Call(FNTYPE_TOOLBAR_CREATE, &arg);
}
/** Checks if this toolbar is visible or not.
* \param hToolbar is the \ref SUHANDLE to the toolbar to query.
* \param visible is a pointer to BOOL that will
* receive the toolbar state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, ToolBar_Create(), FNTYPE_TOOLBAR_ISVISIBLE
*/
inline SURESULT ToolBar_IsVisible(SUHANDLE hToolbar, BOOL *visible)
{
SUARGGetBOOL arg;
arg.hObject = hToolbar;
arg.boolval = visible;
return suapi.ShapeUp_Call(FNTYPE_TOOLBAR_ISVISIBLE, &arg);
}
/** Retrieves the number of buttons in a ShapeUp toolbar.
* \param hToolbar is the \ref SUHANDLE to the toolbar to query.
* \param count is a pointer to size_t that will
* receive the toolbar button count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, ToolBar_Create(), FNTYPE_TOOLBAR_GETBUTTONCOUNT
*/
inline SURESULT ToolBar_GetButtonCount(SUHANDLE hToolbar, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hToolbar;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_TOOLBAR_GETBUTTONCOUNT, &arg);
}
/** Enables or disables a ShapeUp toolbar button.
* \param hToolbar is the \ref SUHANDLE to the toolbar containing the button.
* \param nID is the command ID of the button.
* \param bEnabled is the new enabled state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetButtonBOOL, FNTYPE_TOOLBAR_SETBUTTONENABLED
*/
inline SURESULT ToolBar_SetButtonEnabled(SUHANDLE hToolbar, UINT nID, BOOL bEnabled)
{
SUARGSetButtonBOOL arg;
arg.hToolBar = hToolbar;
arg.hShapeUp = suapi.hShapeUp;
arg.nID = nID;
arg.boolval = bEnabled;
return suapi.ShapeUp_Call(FNTYPE_TOOLBAR_SETBUTTONENABLED, &arg);
}
/** Checkes or unchecks a ShapeUp toolbar button.
* \param hToolbar is the \ref SUHANDLE to the toolbar containing the button.
* \param nID is the command ID of the button.
* \param bChecked is the new checked state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetButtonBOOL, FNTYPE_TOOLBAR_SETBUTTONCHECKED
*/
inline SURESULT ToolBar_SetButtonChecked(SUHANDLE hToolbar, UINT nID, BOOL bChecked)
{
SUARGSetButtonBOOL arg;
arg.hToolBar = hToolbar;
arg.hShapeUp = suapi.hShapeUp;
arg.nID = nID;
arg.boolval = bChecked;
return suapi.ShapeUp_Call(FNTYPE_TOOLBAR_SETBUTTONCHECKED, &arg);
}
/********************************************************************
* ShapeUp API, JavaScript functions implementations
*******************************************************************/
/** Executes a ShapeUp JavaScript.
* \param hJavaScript is the \ref SUHANDLE to the JavaScript to execute.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_HasJavaScriptSupport(), Workspace_LoadJavaScript(),
* FNTYPE_JAVASCRIPT_RUN
*/
inline SURESULT JavaScript_Run(SUHANDLE hJavaScript)
{
return suapi.ShapeUp_Call(FNTYPE_JAVASCRIPT_RUN, hJavaScript);
}
/** Executes a specified funcion in a ShapeUp JavaScript.
* \param hJavaScript is the \ref SUHANDLE to the JavaScript to execute.
* \param name is a null-terminated string containing the name of the
* function to execute. Names are case sensitive.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_HasJavaScriptSupport(), Workspace_LoadJavaScript(),
* SUARGJSCallFunction, FNTYPE_JAVASCRIPT_CALLFUNCTION,
* \ref example_jscallfunction.js "example_jscallfunction.js"
*/
inline SURESULT JavaScript_CallFunction(SUHANDLE hJavaScript, const char *name)
{
SUARGJSCallFunction arg;
arg.hJavaScript = hJavaScript;
arg.name = name;
return suapi.ShapeUp_Call(FNTYPE_JAVASCRIPT_CALLFUNCTION, &arg);
}
/** Closes a ShapeUp JavaScript.
* \param hJavaScript is the \ref SUHANDLE to the JavaScript to close.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa ShapeUp_HasJavaScriptSupport(), Workspace_LoadJavaScript(),
* FNTYPE_JAVASCRIPT_CLOSE
*/
inline SURESULT JavaScript_Close(SUHANDLE hJavaScript)
{
return suapi.ShapeUp_Call(FNTYPE_JAVASCRIPT_CLOSE, hJavaScript);
}
/********************************************************************
* ShapeUp API, Workspace functions implementations
*******************************************************************/
/** Retrieves the ShapeUp map window associated with a workspace.
* \param hWorkspace is the workspace to query.
* \param hMap is a pointer to an \ref SUHANDLE that will
* receive the map window handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, FNTYPE_WORKSPACE_GETMAPWINDOW
*/
inline SURESULT Workspace_GetMapWindow(SUHANDLE hWorkspace, SUHANDLE *hMap)
{
SUARGGetHandle arg;
arg.hObject = hWorkspace;
arg.hResult = hMap;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETMAPWINDOW, &arg);
}
/** Retrieves the number of themes in a ShapeUp workspace.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param count is a pointer to size_t that will
* receive the theme count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_WORKSPACE_GETTHEMECOUNT
*/
inline SURESULT Workspace_GetThemeCount(SUHANDLE hWorkspace, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hWorkspace;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETTHEMECOUNT, &arg);
}
/** Retrieves a theme at a specified index in a ShapeUp workspace.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param nIndex is zero-based index for the theme.
* \param hTheme is a pointer to an \ref SUHANDLE that will
* receive the theme handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandleByIndex, FNTYPE_WORKSPACE_GETTHEMECOUNT
*/
inline SURESULT Workspace_GetTheme(SUHANDLE hWorkspace, size_t nIndex, SUHANDLE *hTheme)
{
SUARGGetHandleByIndex arg;
arg.hObject = hWorkspace;
arg.nIndex = nIndex;
arg.hResult = hTheme;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETTHEME, &arg);
}
/** Retrieves a single selected theme in a ShapeUp workspace. If there
* is exactly one selected theme, this theme will be retrieved,
* otherwise the function returns a NULL \a hTheme handle.\n\n
* This function is a shortcut to check for and get a single
* selected theme supplied since many operations needs just
* one selected theme. To get all selected themes use
* Workspace_GetSelectedThemes().
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param hTheme is a pointer to an \ref SUHANDLE that will
* receive the theme handle, or it will receive a NULL handle if
* there is more or less than one (1) selected theme.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, Workspace_GetSelectedThemes(),
* FNTYPE_WORKSPACE_GETSELECTEDTHEME
*/
inline SURESULT Workspace_GetSelectedTheme(SUHANDLE hWorkspace, SUHANDLE *hTheme)
{
SUARGGetHandle arg;
arg.hObject = hWorkspace;
arg.hResult = hTheme;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETSELECTEDTHEME, &arg);
}
/** Retrieves all selected themes in a ShapeUp workspace. The result
* is in the form of a ShapeUp recordset containing ShapeUp theme
* handles.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param hRecordset is a pointer to an \ref SUHANDLE that will
* receive the recordset handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, Workspace_GetSelectedTheme(),
* FNTYPE_WORKSPACE_GETSELECTEDTHEMES
*/
inline SURESULT Workspace_GetSelectedThemes(SUHANDLE hWorkspace, SUHANDLE *hRecordset)
{
SUARGGetHandle arg;
arg.hObject = hWorkspace;
arg.hResult = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETSELECTEDTHEMES, &arg);
}
/** Retrieves the number of selected themes in a ShapeUp workspace.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param count is a pointer to size_t that will
* receive the selected theme count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_WORKSPACE_GETSELECTIONCOUNT
*/
inline SURESULT Workspace_GetSelectionCount(SUHANDLE hWorkspace, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hWorkspace;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETSELECTIONCOUNT, &arg);
}
/** Creates a new theme of specified sort in a ShapeUp workspace.
* \param hWorkspace is a \ref SUHANDLE to the workspace to add
* the new theme in.
* \param type is the type of objects this theme should contain.
* \param name is a null-terminated string used as the themes initial name.
* This parameter might be NULL to get default naming.
* \param hTheme is a pointer to an \ref SUHANDLE that will
* receive a handle to the new theme.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGCreateNewTheme, FNTYPE_WORKSPACE_CREATENEWTHEME
*/
inline SURESULT Workspace_CreateNewTheme(SUHANDLE hWorkspace, ShapeType type, const char* name, SUHANDLE *hTheme)
{
SUARGCreateNewTheme arg;
arg.hWorkspace = hWorkspace;
arg.type = type;
arg.pszName = name;
arg.hTheme = hTheme;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_CREATENEWTHEME, &arg);
}
/** Creates a new theme based on the selection in a source theme in this workspace.
* \param hWorkspace is a \ref SUHANDLE to the workspace to add
* the new theme in.
* \param hSourceTheme is the theme containing selected shapes to be copied.
* \param name is a null-terminated string used as the themes initial name.
* This parameter might be NULL to get default naming.
* \param hTheme is a pointer to an \ref SUHANDLE that will
* receive a handle to the new theme.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGCreateNewThemeFromSelection, FNTYPE_WORKSPACE_CREATENEWTHEMEFROMSELECTION
*/
inline SURESULT Workspace_CreateNewThemeFromSelection(SUHANDLE hWorkspace, SUHANDLE hSourceTheme, const char* name, SUHANDLE *hTheme)
{
SUARGCreateNewThemeFromSelection arg;
arg.hWorkspace = hWorkspace;
arg.hSourceTheme = hSourceTheme;
arg.pszName = name;
arg.hResultTheme = hTheme;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_CREATENEWTHEMEFROMSELECTION, &arg);
}
/** Gets the workspace's bounding box.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param xmin is a pointer to a double that will receive the west-most value.
* This parameter might be NULL if it's of no interest.
* \param ymin is a pointer to a double that will receive the south-most value.
* This parameter might be NULL if it's of no interest.
* \param xmax is a pointer to a double that will receive the east-most value.
* This parameter might be NULL if it's of no interest.
* \param ymax is a pointer to a double that will receive the north-most value.
* This parameter might be NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBounds, FNTYPE_WORKSPACE_GETBOUNDS
*/
inline SURESULT Workspace_GetBounds(SUHANDLE hWorkspace, double *xmin, double *ymin, double *xmax, double *ymax)
{
SUARGGetBounds arg;
arg.hObject = hWorkspace;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETBOUNDS, &arg);
}
/** Writes a text to a workspace's console window. It does not end the
* text with a new line. If a new line is required the character '\\n'
* should be supplied in the text.
* \param hWorkspace is the \ref SUHANDLE to the workspace that contains
* the console.
* \param line is a null-terminated string to be sent to the console
* window.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGLog, FNTYPE_WORKSPACE_LOG
*/
inline SURESULT Workspace_Log(SUHANDLE hWorkspace, const char *line)
{
SUARGLog arg;
arg.hWorkspace = hWorkspace;
arg.line = line;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_LOG, &arg);
}
/** Retrieves the active state of a ShapeUp workspace. A ShapeUp
* workspace is considered active if it has the input focus.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param active is a pointer to a BOOL that will receive the active
* state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_WORKSPACE_ISACTIVE
*/
inline SURESULT Workspace_IsActive(SUHANDLE hWorkspace, BOOL *active)
{
SUARGGetBOOL arg;
arg.hObject = hWorkspace;
arg.boolval = active;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_ISACTIVE, &arg);
}
/** Opens ShapeUp's theme selection dialog and lets the user select a
* theme.
* \param hWorkspace is the \ref SUHANDLE to the workspace containing
* the themes.
* \param title is a null-terminated string containing the title for
* the dialog. Might be NULL if default title "Select Theme" is ok.
* \param hTheme is a pointer to an \ref SUHANDLE that will
* receive the theme handle. This handle will be NULL if the user
* presses cancel.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGBrowseTheme, FNTYPE_WORKSPACE_BROWSETHEME
*/
inline SURESULT Workspace_BrowseTheme(SUHANDLE hWorkspace, const char* title, SUHANDLE *hTheme)
{
SUARGBrowseTheme arg;
arg.hWorkspace = hWorkspace;
arg.pszTitle = title;
arg.hTheme = hTheme;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_BROWSETHEME, &arg);
}
/** Forces the entire workspace to update its user interface components,
* such as the legend view, map view and data view.
* \param hWorkspace is the \ref SUHANDLE to the workspace to refresh.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_WORKSPACE_REFRESH
*/
inline SURESULT Workspace_Refresh(SUHANDLE hWorkspace)
{
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_REFRESH, hWorkspace);
}
/** Loads a JavaScript.
* \param hWorkspace is the \ref SUHANDLE to the workspace that will
* become the target of the JavaScript.
* \param file is a null-terminated string containing the file name
* of the JavaScript.
* \param hJavaScript is a pointer to an \ref SUHANDLE that will
* receive the JavaScript handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGLoadJavaScript, FNTYPE_WORKSPACE_LOADJAVASCRIPT,
* JavaScript_Run(), JavaScript_CallFunction(), JavaScript_Close()
*/
inline SURESULT Workspace_LoadJavaScript(SUHANDLE hWorkspace, const char* file, SUHANDLE *hJavaScript)
{
SUARGLoadJavaScript arg;
arg.hWorkspace = hWorkspace;
arg.file = file;
arg.hJavaScript = hJavaScript;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_LOADJAVASCRIPT, &arg);
}
/** Retrieves a workspace's comment.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the comment, then the actual comment can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hWorkspace is the \ref SUHANDLE to the workspace to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetText, FNTYPE_WORKSPACE_GETCOMMENT
*/
inline SURESULT Workspace_GetComment(SUHANDLE hWorkspace, char *buffer, size_t *bufferSize)
{
SUARGGetText arg;
arg.hObject = hWorkspace;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_GETCOMMENT, &arg);
}
/** Sets a workspace's comment.
* \param hWorkspace is the \ref SUHANDLE to the workspace.
* \param buffer is a null-terminated string that contains the new comment.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetText, FNTYPE_WORKSPACE_SETCOMMENT
*/
inline SURESULT Workspace_SetComment(SUHANDLE hWorkspace, const char *buffer)
{
SUARGSetText arg;
arg.hObject = hWorkspace;
arg.buffer = buffer;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_SETCOMMENT, &arg);
}
/** Removes a theme from a workspace.
* \param hWorkspace is the \ref SUHANDLE to the workspace.
* \param hTheme is the \ref SUHANDLE to the theme to remove.
* \param ok is a pointer to a BOOL that will receive the success of
* the operation.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGRemoveTheme, FNTYPE_WORKSPACE_REMOVETHEME
*/
inline SURESULT Workspace_RemoveTheme(SUHANDLE hWorkspace, SUHANDLE hTheme, BOOL *ok)
{
SUARGRemoveTheme arg;
arg.hWorkspace = hWorkspace;
arg.hTheme = hTheme;
arg.ok = ok;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_REMOVETHEME, &arg);
}
/** Sets data to be serialized with a workspace. This function can be
* called at any time setting new data. However, when this function
* is called, any old data is discarded and fully replaced with the
* new.\n
* This data can later be restored from a ShapeUp workspace file
* when it is loaded, if the plug-in has set up a deserialize hook
* using the ShapeUp_AddDeserializeHook call.
* \param hWorkspace is the \ref SUHANDLE to the workspace.
* \param byteCount is the size of the \a bytes array.
* \param bytes is a pointer to a byte sequence containing the data to
* be serialized.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetSerialData, FNTYPE_WORKSPACE_SETSERIALDATA,
* ShapeUp_AddDeserializeHook()
*/
inline SURESULT Workspace_SetSerialData(SUHANDLE hWorkspace, size_t byteCount, const void *bytes)
{
SUARGSetSerialData arg;
arg.hShapeUp = suapi.hShapeUp;
arg.hObject = hWorkspace;
arg.byteCount = byteCount;
arg.bytes = bytes;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_SETSERIALDATA, &arg);
}
/** Creates a new custom data page for a workspace. A data page is an addition
* to the four native data pages supplied by ShapeUp: Attributes,
* Coordinates, Statistics and Bookmarks.\n
* A custom data page can be used to display any windows control as a
* child.
* \param hWorkspace is the \ref SUHANDLE to the workspace.
* \param name is the name of the new data page. This name is displayed in
* the view menu as well as in the Quick Tabs.
* \param page is a pointer to a windows handle to be used as the parent of the new
* the new child control. This parameter might be NULL.
* \param hDataPage is a SUHANDLE that will identify the created data page. This
* parameter might be NULL.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAddDataPage, FNTYPE_WORKSPACE_ADDDATAPAGE
*/
inline SURESULT Workspace_AddDataPage(SUHANDLE hWorkspace, const char *name, HWND *page, SUHANDLE *hDataPage)
{
SUARGAddDataPage arg;
arg.hWorkspace = hWorkspace;
arg.name = name;
arg.page = page;
arg.hDataPage = hDataPage;
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_ADDDATAPAGE, &arg);
}
/** Deselects all themes in a workspace.
* \param hWorkspace is the \ref SUHANDLE to the workspace.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_WORKSPACE_CLEARSELECTION
*/
inline SURESULT Workspace_ClearSelection(SUHANDLE hWorkspace)
{
return suapi.ShapeUp_Call(FNTYPE_WORKSPACE_CLEARSELECTION, hWorkspace);
}
/********************************************************************
* ShapeUp API, DataPage functions implementations
*******************************************************************/
/** Removes a custom data page for a workspace. A data page is an addition
* to the four native data pages supplied by ShapeUp: Attributes,
* Coordinates, Statistics and Bookmarks.\n
* A custom data page can be used to display any windows control as a
* child.
* \param hDataPage is an \ref SUHANDLE to the data page to remove.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_DATAPAGE_REMOVE, Workspace_AddDataPage()
*/
inline SURESULT DataPage_Remove(SUHANDLE hDataPage)
{
return suapi.ShapeUp_Call(FNTYPE_DATAPAGE_REMOVE, hDataPage);
}
/** Retrievs the window handle to the ShapeUp map window.
* \param hDataPage is the \ref SUHANDLE to the custom data page.
* \param hWnd is a pointer to a HWND that will receive the data page
* window handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHWND, FNTYPE_DATAPAGE_GETHWND
*/
inline SURESULT DataPage_GetHWND(SUHANDLE hDataPage, HWND *hWnd)
{
SUARGGetHWND arg;
arg.hObject = hDataPage;
arg.hWnd = hWnd;
return suapi.ShapeUp_Call(FNTYPE_DATAPAGE_GETHWND, &arg);
}
/********************************************************************
* ShapeUp API, Map functions implementations
*******************************************************************/
/** Gets the map's bounding box.
* \param hMap is the \ref SUHANDLE to the ShapeUp map to query.
* \param xmin is a pointer to a double that will receive the west-most value.
* \param ymin is a pointer to a double that will receive the south-most value.
* \param xmax is a pointer to a double that will receive the east-most value.
* \param ymax is a pointer to a double that will receive the north-most value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBounds, FNTYPE_MAP_GETBOUNDS
*/
inline SURESULT Map_GetBounds(SUHANDLE hMap, double *xmin, double *ymin, double *xmax, double *ymax)
{
SUARGGetBounds arg;
arg.hObject = hMap;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
return suapi.ShapeUp_Call(FNTYPE_MAP_GETBOUNDS, &arg);
}
/** Gets the map's view size in device units.
* \param hMap is the \ref SUHANDLE to the ShapeUp map to query.
* \param width is a pointer to a size_t that will receive the width in device units.
* \param height is a pointer to a size_t that will receive the height in device units.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetSize, FNTYPE_MAP_GETVIEWSIZE
*/
inline SURESULT Map_GetViewSize(SUHANDLE hMap, size_t *width, size_t *height)
{
SUARGGetSize arg;
arg.hObject = hMap;
arg.width = width;
arg.height = height;
return suapi.ShapeUp_Call(FNTYPE_MAP_GETVIEWSIZE, &arg);
}
/** Converts a geographical point to a device point.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param gpx is a double that contains the east-west value to convert.
* \param gpy is a double that contains the north-south value to convert.
* \param dpx is a pointer to an int that will receive the east-west value.
* \param dpy is a pointer to an int that will receive the north-south value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGPtoDP, FNTYPE_MAP_GPTODP
*/
inline SURESULT Map_GPtoDP(SUHANDLE hMap, double gpx, double gpy, int *dpx, int *dpy)
{
SUARGGPtoDP arg;
arg.hMap = hMap;
arg.gpx = gpx;
arg.gpy = gpy;
arg.dpx = dpx;
arg.dpy = dpy;
return suapi.ShapeUp_Call(FNTYPE_MAP_GPTODP, &arg);
}
/** Converts a device point to a geographical point.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param dpx is an int that contains the east-west value to convert.
* \param dpy is an int that contains the north-south value to convert.
* \param gpx is a pointer to a double that will receive the east-west value.
* \param gpy is a pointer to a double that will receive the north-south value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGDPtoGP, FNTYPE_MAP_DPTOGP
*/
inline SURESULT Map_DPtoGP(SUHANDLE hMap, int dpx, int dpy, double *gpx, double *gpy)
{
SUARGDPtoGP arg;
arg.hMap = hMap;
arg.dpx = dpx;
arg.dpy = dpy;
arg.gpx = gpx;
arg.gpy = gpy;
return suapi.ShapeUp_Call(FNTYPE_MAP_DPTOGP, &arg);
}
/** Retrievs the window handle to the ShapeUp map window.
* \param hMap is the \ref SUHANDLE to the ShapeUp map to query.
* \param hWnd is a pointer to a HWND that will receive the map window handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHWND, FNTYPE_MAP_GETHWND
*/
inline SURESULT Map_GetHWND(SUHANDLE hMap, HWND *hWnd)
{
SUARGGetHWND arg;
arg.hObject = hMap;
arg.hWnd = hWnd;
return suapi.ShapeUp_Call(FNTYPE_MAP_GETHWND, &arg);
}
/** Forces a repaint of the ShapeUp map window.
* \param hMap is the \ref SUHANDLE to the ShapeUp map to refresh.
* \param bFullRedraw if true, all map objects are redrawn, and if
* false, the background buffer is used to paint the map objects
* and only the top items are redrawn.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGRepaint, FNTYPE_MAP_REPAINT
*/
inline SURESULT Map_Repaint(SUHANDLE hMap, BOOL bFullRedraw)
{
SUARGRepaint arg;
arg.hMap = hMap;
arg.bFullRedraw = bFullRedraw;
return suapi.ShapeUp_Call(FNTYPE_MAP_REPAINT, &arg);
}
/** Draws a ShapeUp workspace to an external Windows device context.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param hdc is a handle to the target Windows device context.
* \param iw is the width in device units of the image to draw.
* \param ih is the height in device units of the image to draw.
* \param x is the center point east-west component.
* \param y is the center point north-south component.
* \param gw is the east-west geographical extent.
* \param gh is the north-south geographical extent.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGDraw, FNTYPE_MAP_DRAW
*/
inline SURESULT Map_Draw(SUHANDLE hMap, HDC hdc, size_t iw, size_t ih, double x, double y, double gw, double gh)
{
SUARGDraw arg;
arg.hMap = hMap;
arg.hdc = hdc;
arg.imageWidth = iw;
arg.imageHeight = ih;
arg.xCenter = x;
arg.yCenter = y;
arg.geoWidth = gw;
arg.geoHeight = gh;
return suapi.ShapeUp_Call(FNTYPE_MAP_DRAW, &arg);
}
/** Centers the ShapeUp map window around a point.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param x is the new center point east-west component.
* \param y is the new center point north-south component.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetPoint, FNTYPE_MAP_CENTERMAP
*/
inline SURESULT Map_CenterMap(SUHANDLE hMap, double x, double y)
{
SUARGSetPoint arg;
arg.hObject = hMap;
arg.x = x;
arg.y = y;
return suapi.ShapeUp_Call(FNTYPE_MAP_CENTERMAP, &arg);
}
/** Zooms the map.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param factor is the factor used to zoom the map. 0.0 < factor < 1.0 zooms in,
* and 1.0 < factor zooms out.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetDouble, FNTYPE_MAP_ZOOM
*/
inline SURESULT Map_Zoom(SUHANDLE hMap, double factor)
{
SUARGSetDouble arg;
arg.hObject = hMap;
arg.doubleval = factor;
return suapi.ShapeUp_Call(FNTYPE_MAP_ZOOM, &arg);
}
/** Zooms the map to fit the selection in a specified theme.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme that
* contains the selection.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGZoomToSelection, FNTYPE_MAP_ZOOMTOSELECTION
*/
inline SURESULT Map_ZoomToSelection(SUHANDLE hMap, SUHANDLE hTheme)
{
SUARGZoomToSelection arg;
arg.hMap = hMap;
arg.hTheme = hTheme;
return suapi.ShapeUp_Call(FNTYPE_MAP_ZOOMTOSELECTION, &arg);
}
/** Zooms the map to fit the entire workspace, or to fit a specified
* theme.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to fit.
* If this parameter is NULL, the map will zoom to fit the entire
* workspace.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGZoomToExtent, FNTYPE_MAP_ZOOMTOEXTENT
*/
inline SURESULT Map_ZoomToExtent(SUHANDLE hMap, SUHANDLE hTheme)
{
SUARGZoomToExtent arg;
arg.hMap = hMap;
arg.hTheme = hTheme;
return suapi.ShapeUp_Call(FNTYPE_MAP_ZOOMTOEXTENT, &arg);
}
/** Retrieves the current map interaction state. The interaction state
* is a value indicating what the user is about to do, or is doing,
* in the map. This is in short the state of the mutual exclusive
* toolbar buttons like select, rectangle select, circle select, etc.
* This can be used to add new states to the map.
* \param hMap is the \ref SUHANDLE to the ShapeUp map to query.
* \param state is a pointer to an unsigned long that will receive the
* current map interaction state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetInteractionState, Map_SetInteractionState(), \ref MAPSTATE,
* FNTYPE_MAP_GETINTERACTIONSTATE
*/
inline SURESULT Map_GetInteractionState(SUHANDLE hMap, unsigned long *state)
{
SUARGGetInteractionState arg;
arg.hMap = hMap;
arg.hShapeUp = suapi.hShapeUp;
arg.state = state;
return suapi.ShapeUp_Call(FNTYPE_MAP_GETINTERACTIONSTATE, &arg);
}
/** Sets a new map interaction state. The interaction state
* is a value indicating what the user is about to do, or is doing,
* in the map. This is in short the state of the mutual exclusive
* toolbar buttons like select, rectangle select, circle select, etc.
* This can be used to add new states to the map.
* \param hMap is the \ref SUHANDLE to the ShapeUp map.
* \param state is an unsigned long containing the new map interaction
* state. Note: Not all map states defined can be set.
* Check \ref MAPSTATE for more info.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetInteractionState, Map_GetInteractionState(), \ref MAPSTATE,
* FNTYPE_MAP_SETINTERACTIONSTATE
*/
inline SURESULT Map_SetInteractionState(SUHANDLE hMap, unsigned long state)
{
SUARGSetInteractionState arg;
arg.hMap = hMap;
arg.hShapeUp = suapi.hShapeUp;
arg.state = state;
return suapi.ShapeUp_Call(FNTYPE_MAP_SETINTERACTIONSTATE, &arg);
}
/********************************************************************
* ShapeUp API, Theme functions implementations
*******************************************************************/
/** Adds a copy of a new shape object to a theme.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme.
* \param shapeData is a pointer to the new shape object to add.
* \param hShape is a pointer to a \ref SUHANDLE that will receive a
* handle to the new shape object.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAddShape, FNTYPE_THEME_ADDSHAPE
*/
inline SURESULT Theme_AddShape(SUHANDLE hTheme, const CShapeRecord *shapeData, SUHANDLE *hShape)
{
SUARGAddShape arg;
arg.hTheme = hTheme;
arg.shapeData = shapeData;
arg.hShape = hShape;
return suapi.ShapeUp_Call(FNTYPE_THEME_ADDSHAPE, &arg);
}
/** Turns off indexing and other time consuming tasks when calling Theme_AddShape().
* Use this if many shapes should be added at once. After the
* shapes have been added, call Theme_BatchAddShapeEnd() to turn the
* features back on again.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme.
* \sa Theme_AddShape(), Theme_BatchAddShapeEnd()
*/
inline SURESULT Theme_BatchAddShapeBegin(SUHANDLE hTheme)
{
SUARGBatchAddShape arg;
arg.hShapeUp = suapi.hShapeUp;
arg.hTheme = hTheme;
arg.index_on = FALSE;
return suapi.ShapeUp_Call(FNTYPE_THEME_BATCHADDSHAPE, &arg);
}
/** Turns on indexing and other tasks after calling Theme_AddShape().
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme.
* \sa Theme_AddShape(), Theme_BatchAddShapeBegin()
*/
inline SURESULT Theme_BatchAddShapeEnd(SUHANDLE hTheme)
{
SUARGBatchAddShape arg;
arg.hShapeUp = suapi.hShapeUp;
arg.hTheme = hTheme;
arg.index_on = TRUE;
return suapi.ShapeUp_Call(FNTYPE_THEME_BATCHADDSHAPE, &arg);
}
/** Replaces the geometry of a shape object in a theme with a new
* geometry.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme.
* \param hShape is a \ref SUHANDLE to the shape object to replace.
* \param shapeData is a pointer to the new shape object to insert.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGReplaceShapeData, FNTYPE_THEME_REPLACESHAPEDATA
*/
inline SURESULT Theme_ReplaceShapeData(SUHANDLE hTheme, SUHANDLE hShape, const CShapeRecord *shapeData)
{
SUARGReplaceShapeData arg;
arg.hTheme = hTheme;
arg.hShape = hShape;
arg.shapeData = shapeData;
return suapi.ShapeUp_Call(FNTYPE_THEME_REPLACESHAPEDATA, &arg);
}
/** Deletes a shape within a ShapeUp theme. After this operation, the
* \a hShape handle will be invalid.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme containing
* the shape object to delete.
* \param hShape is a \ref SUHANDLE to the shape object to delete.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGDeleteShape, FNTYPE_THEME_DELETESHAPE
*/
inline SURESULT Theme_DeleteShape(SUHANDLE hTheme, SUHANDLE hShape)
{
SUARGDeleteShape arg;
arg.hTheme = hTheme;
arg.hShape = hShape;
return suapi.ShapeUp_Call(FNTYPE_THEME_DELETESHAPE, &arg);
}
/** Determines if a theme is selected.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to query.
* \param selected is a pointer to a BOOL that will receive the selected
* state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_THEME_ISSELECTED
*/
inline SURESULT Theme_IsSelected(SUHANDLE hTheme, BOOL *selected)
{
SUARGGetBOOL arg;
arg.hObject = hTheme;
arg.boolval = selected;
return suapi.ShapeUp_Call(FNTYPE_THEME_ISSELECTED, &arg);
}
/** Determines if a theme is read-only.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to query.
* \param readonly is a pointer to a BOOL that will receive the
* read-only state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_THEME_ISREADONLY
*/
inline SURESULT Theme_IsReadOnly(SUHANDLE hTheme, BOOL *readonly)
{
SUARGGetBOOL arg;
arg.hObject = hTheme;
arg.boolval = readonly;
return suapi.ShapeUp_Call(FNTYPE_THEME_ISREADONLY, &arg);
}
/** Determines if a theme is visible.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to query.
* \param visible is a pointer to a BOOL that will receive the
* visibility state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_THEME_ISVISIBLE
*/
inline SURESULT Theme_IsVisible(SUHANDLE hTheme, BOOL *visible)
{
SUARGGetBOOL arg;
arg.hObject = hTheme;
arg.boolval = visible;
return suapi.ShapeUp_Call(FNTYPE_THEME_ISVISIBLE, &arg);
}
/** Retrieves the name of a ShapeUp theme.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the name, then the actual name can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetText, FNTYPE_THEME_GETNAME
*/
inline SURESULT Theme_GetName(SUHANDLE hTheme, char *buffer, size_t *bufferSize)
{
SUARGGetText arg;
arg.hObject = hTheme;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETNAME, &arg);
}
/** Sets the name of a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param buffer is a null-terminated string that contains the new name.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetText, FNTYPE_THEME_SETNAME
*/
inline SURESULT Theme_SetName(SUHANDLE hTheme, const char *buffer)
{
SUARGSetText arg;
arg.hObject = hTheme;
arg.buffer = buffer;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETNAME, &arg);
}
/** Retrieves the name of an attribute in a ShapeUp theme.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the name, then the actual name can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param column is the zero-based index of the attribute to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetText, FNTYPE_THEME_GETATTRIBUTENAME
*/
inline SURESULT Theme_GetAttributeName(SUHANDLE hTheme, size_t column, char *buffer, size_t *bufferSize)
{
SUARGGetTextByIndex arg;
arg.hObject = hTheme;
arg.index = column;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETATTRIBUTENAME, &arg);
}
/** Retrieves the type of an attribute in a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param column is the zero-based index of the attribute to query.
* \param type is a pointer to an unsigned long which will receive the type value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetAttributeType, FNTYPE_THEME_GETATTRIBUTETYPE, \ref ATTRIBUTETYPE
*/
inline SURESULT Theme_GetAttributeType(SUHANDLE hTheme, size_t column, unsigned long *type)
{
SUARGGetAttributeType arg;
arg.hTheme = hTheme;
arg.index = column;
arg.type = type;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETATTRIBUTETYPE, &arg);
}
/** Retrieves the index of a named attribute in a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param name is a null-terminated string containing the name of the attribute to query.
* \param index is a pointer to a size_t which will receive the index value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function. A return value of
* SURESULT_FALSE means the lookup failed.
* \sa SUARGGetAttributeIndex, FNTYPE_THEME_GETATTRIBUTEINDEX
*/
inline SURESULT Theme_GetAttributeIndex(SUHANDLE hTheme, const char* name, size_t *index)
{
SUARGGetAttributeIndex arg;
arg.hTheme = hTheme;
arg.name = name;
arg.index = index;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETATTRIBUTEINDEX, &arg);
}
/** Retrieves the number of attributes in a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param count is a pointer to size_t that will
* receive the attribute count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_THEME_GETATTRIBUTECOUNT
*/
inline SURESULT Theme_GetAttributeCount(SUHANDLE hTheme, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETATTRIBUTECOUNT, &arg);
}
/** Retrieves the number of shape objects in a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param count is a pointer to size_t that will
* receive the shape object count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_THEME_GETSHAPECOUNT
*/
inline SURESULT Theme_GetShapeCount(SUHANDLE hTheme, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPECOUNT, &arg);
}
/** Gets a shape from a theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param nIndex is the zero-based index of the shape whithin the theme.
* \param hShape is a pointer to an \ref SUHANDLE that will receive
* the shape handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandleByIndex, FNTYPE_THEME_GETSHAPE,
* Theme_GetShapeCount()
*/
inline SURESULT Theme_GetShape(SUHANDLE hTheme, size_t nIndex, SUHANDLE *hShape)
{
SUARGGetHandleByIndex arg;
arg.hObject = hTheme;
arg.nIndex = nIndex;
arg.hResult = hShape;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPE, &arg);
}
/** Gets a shape from a theme looking it up by its internal index identifier.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param nIndex is the shape's internal index identifier.
* \param hShape is a pointer to an \ref SUHANDLE that will receive
* the shape handle.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandleByIndex, FNTYPE_THEME_GETSHAPEFROMINDEX,
* Theme_GetShape()
*/
inline SURESULT Theme_GetShapeFromIndex(SUHANDLE hTheme, size_t nIndex, SUHANDLE *hShape)
{
SUARGGetHandleByIndex arg;
arg.hObject = hTheme;
arg.nIndex = nIndex;
arg.hResult = hShape;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPEFROMINDEX, &arg);
}
/** Retrieves the type of shapes this theme contains.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param type is a pointer to a ShapeType that will receive
* the theme's shape type.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapeType, FNTYPE_THEME_GETSHAPETYPE,
*/
inline SURESULT Theme_GetShapeType(SUHANDLE hTheme, ShapeType *type)
{
SUARGGetShapeType arg;
arg.hObject = hTheme;
arg.type = type;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPETYPE, &arg);
}
/** Gets the themes's bounding box.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to query.
* \param xmin is a pointer to a double that will receive the west-most value.
* This parameter might be NULL if it's of no interest.
* \param ymin is a pointer to a double that will receive the south-most value.
* This parameter might be NULL if it's of no interest.
* \param xmax is a pointer to a double that will receive the east-most value.
* This parameter might be NULL if it's of no interest.
* \param ymax is a pointer to a double that will receive the north-most value.
* This parameter might be NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBounds, FNTYPE_THEME_GETBOUNDS
*/
inline SURESULT Theme_GetBounds(SUHANDLE hTheme, double *xmin, double *ymin, double *xmax, double *ymax)
{
SUARGGetBounds arg;
arg.hObject = hTheme;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETBOUNDS, &arg);
}
/** Recalculates a themes's bounding box. This function needs to be called after
* the geometry of a contained object is changed.
* \param hTheme is the \ref SUHANDLE to the ShapeUp theme to update.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_THEME_RECALCBOUNDS
*/
inline SURESULT Theme_RecalcBounds(SUHANDLE hTheme)
{
return suapi.ShapeUp_Call(FNTYPE_THEME_RECALCBOUNDS, hTheme);
}
/** Gets all shapes from a theme intersecting a specific shape. If the
* shape indicated by \a hShape is in the searched theme, \a hTheme,
* that shape will not be included in the result.\n\n
* IMPORTANT: Retrieved recordsets must be closed by a call to
* Recordset_Close().
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param hShape is the \ref SUHANDLE to the shape that will be
* used for intersection tests.
* \param hRecordset is a pointer to an \ref SUHANDLE that will receive
* a handle to a recordset containing the intersecting shapes.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandleByIndex, FNTYPE_THEME_GETSHAPEFROMINDEX,
* Theme_GetShape()
*/
inline SURESULT Theme_GetIntersectingShapes(SUHANDLE hTheme, SUHANDLE hShape, SUHANDLE *hRecordset)
{
SUARGGetIntersectingShapes arg;
arg.hTheme = hTheme;
arg.hShape = hShape;
arg.hRecordset = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETINTERSECTINGSHAPES, &arg);
}
/** Gets all shapes from a theme contained in or intersecting a rectangle.\n\n
* IMPORTANT: Retrieved recordsets must be closed by a call to
* Recordset_Close().
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param xmin is the west-most bound of the rectangle.
* \param ymin is the south-most bound of the rectangle.
* \param xmax is the east-most bound of the rectangle.
* \param ymax is the north-most bound of the rectangle.
* \param bPartInRectOk if true, this function returns a recordset containing
* all shapes that intersects the specified rectangle. If false, it will
* return all shapes that are contained in the rectangle.
* \param hRecordset is a pointer to an \ref SUHANDLE that will receive
* a handle to a recordset containing the resulting shapes.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapesInRect, FNTYPE_THEME_GETSHAPESINRECT,
* Theme_GetShape()
*/
inline SURESULT Theme_GetShapesInRect(SUHANDLE hTheme, double xmin, double ymin, double xmax, double ymax, BOOL bPartInRectOk, SUHANDLE *hRecordset)
{
SUARGGetShapesInRect arg;
arg.hTheme = hTheme;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
arg.bPartInRectOk = bPartInRectOk;
arg.hRecordset = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPESINRECT, &arg);
}
/** Retrieves the number of selected shape objects in a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param count is a pointer to size_t that will
* receive the selected shape object count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_THEME_GETSELECTIONCOUNT
*/
inline SURESULT Theme_GetSelectionCount(SUHANDLE hTheme, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSELECTIONCOUNT, &arg);
}
/** Gets all selected shapes from a ShapeUp theme.\n\n
* IMPORTANT: Retrieved recordsets must be closed by a call to
* Recordset_Close().
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param hRecordset is a pointer to an \ref SUHANDLE that will receive
* a handle to a recordset containing the selected shapes.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, FNTYPE_THEME_GETSELECTEDSHAPES,
* Theme_GetShape()
*/
inline SURESULT Theme_GetSelectedShapes(SUHANDLE hTheme, SUHANDLE *hRecordset)
{
SUARGGetHandle arg;
arg.hObject = hTheme;
arg.hResult = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSELECTEDSHAPES, &arg);
}
/** Gets all selected shapes from a theme contained in or intersecting a
* rectangle.\n\n
* IMPORTANT: Retrieved recordsets must be closed by a call to
* Recordset_Close().
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param xmin is the west-most bound of the rectangle.
* \param ymin is the south-most bound of the rectangle.
* \param xmax is the east-most bound of the rectangle.
* \param ymax is the north-most bound of the rectangle.
* \param bPartInRectOk if true, this function returns a recordset containing
* all selected shapes that intersects the specified rectangle. If false,
* it will return all selected shapes that are contained in the rectangle.
* \param hRecordset is a pointer to an \ref SUHANDLE that will receive
* a handle to a recordset containing the resulting shapes.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapesInRect, FNTYPE_THEME_GETSELECTEDSHAPESINRECT,
* Theme_GetShape()
*/
inline SURESULT Theme_GetSelectedShapesInRect(SUHANDLE hTheme, double xmin, double ymin, double xmax, double ymax, BOOL bPartInRectOk, SUHANDLE *hRecordset)
{
SUARGGetShapesInRect arg;
arg.hTheme = hTheme;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
arg.bPartInRectOk = bPartInRectOk;
arg.hRecordset = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSELECTEDSHAPESINRECT, &arg);
}
/** Retrieves the translated InfoTip of a shape in a ShapeUp theme.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the text, then the actual text can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hTheme is the \ref SUHANDLE to the theme containing the shape.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetInfoTip, FNTYPE_THEME_GETINFOTIP
*/
inline SURESULT Theme_GetInfoTip(SUHANDLE hTheme, SUHANDLE hShape, char *buffer, size_t *bufferSize)
{
SUARGGetInfoTip arg;
arg.hTheme = hTheme;
arg.hShape = hShape;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETINFOTIP, &arg);
}
/** Retrieves font information used for labels from a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param font is a pointer to a LOGFON struct that will receive the
* font properties.
* This parameter might be NULL if it's of no interest.
* \param clr is a pointer to a COLORREF that will receive the text color.
* This parameter might be NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetInfoTip, FNTYPE_THEME_GETINFOTIP
*/
inline SURESULT Theme_GetFont(SUHANDLE hTheme, LOGFONT *font, COLORREF *clr)
{
SUARGGetFont arg;
arg.hObject = hTheme;
arg.font = font;
arg.clr = clr;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETFONT, &arg);
}
/** Gets all selected shapes from a theme matching attributes.\n\n
* IMPORTANT: Retrieved recordsets must be closed by a call to
* Recordset_Close().
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param where is a null-terminated string containing a SQL-like where
* statement, as can be found in the ShapeUp Query Dialog, to use for matching.
* \param hRecordset is a pointer to an \ref SUHANDLE that will receive
* a handle to a recordset containing the matching shapes.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapesByQuery, FNTYPE_THEME_GETSHAPESBYQUERY,
* Theme_GetShape()
*/
inline SURESULT Theme_GetShapesByQuery(SUHANDLE hTheme, const char *where, SUHANDLE *hRecordset)
{
SUARGGetShapesByQuery arg;
arg.hTheme = hTheme;
arg.where = where;
arg.hRecordset = hRecordset;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETSHAPESBYQUERY, &arg);
}
/** Retrievs the workspace containing the ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to a theme.
* \param hWorkspace is a pointer to an \ref SUHANDLE that will receive
* a handle to the hosting workspace.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, FNTYPE_THEME_LOOKUPWORKSPACE
*/
inline SURESULT Theme_LookupWorkspace(SUHANDLE hTheme, SUHANDLE *hWorkspace)
{
SUARGGetHandle arg;
arg.hObject = hTheme;
arg.hResult = hWorkspace;
return suapi.ShapeUp_Call(FNTYPE_THEME_LOOKUPWORKSPACE, &arg);
}
/** Adds a new attribute to a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param type is the \ref ATTRIBUTETYPE of the new attribute.
* \param name is null-terminated string containing the name of the
* new attribute. This parameter cannot be NULL nor an empty string.
* \param defaultval is null-terminated string containing a default value
* of the new attribute. This parameter might be NULL.
* \param index is a pointer to a size_t that will receive the zero-based
* index of the added attribute.
* This parameter might be NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGAddAttribute, FNTYPE_THEME_ADDATTRIBUTE, \ref ATTRIBUTETYPE
*/
inline SURESULT Theme_AddAttribute(SUHANDLE hTheme, unsigned long type, const char *name, const char *defaultval, size_t *index)
{
SUARGAddAttribute arg;
arg.hTheme = hTheme;
arg.type = type;
arg.name = name;
arg.defaultval = defaultval;
arg.index = index;
return suapi.ShapeUp_Call(FNTYPE_THEME_ADDATTRIBUTE, &arg);
}
/** Deletes an attribute from a ShapeUp theme.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param index is the zero-based index of the attribute to delete.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGDeleteAttribute, FNTYPE_THEME_DELETEATTRIBUTE
*/
inline SURESULT Theme_DeleteAttribute(SUHANDLE hTheme, size_t index)
{
SUARGDeleteAttribute arg;
arg.hTheme = hTheme;
arg.index = index;
return suapi.ShapeUp_Call(FNTYPE_THEME_DELETEATTRIBUTE, &arg);
}
/** Sets an attribute's comment.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param index is the zero-based index of the attribute.
* \param buffer is a null-terminated string that contains the new comment.
* Use NULL to clear the comment.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetTextByIndex, FNTYPE_THEME_SETATTRIBUTECOMMENT
*/
inline SURESULT Theme_SetAttributeComment(SUHANDLE hTheme, size_t index, const char *buffer)
{
SUARGSetTextByIndex arg;
arg.hObject = hTheme;
arg.index = index;
arg.buffer = buffer;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETATTRIBUTECOMMENT, &arg);
}
/** Retrieves a theme's comment.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the comment, then the actual comment can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hTheme is the \ref SUHANDLE to the theme to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetText, FNTYPE_THEME_GETCOMMENT
*/
inline SURESULT Theme_GetComment(SUHANDLE hTheme, char *buffer, size_t *bufferSize)
{
SUARGGetText arg;
arg.hObject = hTheme;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETCOMMENT, &arg);
}
/** Sets a theme's comment.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param buffer is a null-terminated string that contains the new comment.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetText, FNTYPE_THEME_SETCOMMENT
*/
inline SURESULT Theme_SetComment(SUHANDLE hTheme, const char *buffer)
{
SUARGSetText arg;
arg.hObject = hTheme;
arg.buffer = buffer;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETCOMMENT, &arg);
}
/** Gets a theme's pen color.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param clr is a pointer to a COLORREF value that will receive the
* current pen color.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetColor, FNTYPE_THEME_GETPENCOLOR
*/
inline SURESULT Theme_GetPenColor(SUHANDLE hTheme, COLORREF *clr)
{
SUARGGetColor arg;
arg.hObject = hTheme;
arg.clr = clr;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETPENCOLOR, &arg);
}
/** Sets a theme's pen color.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param clr is a COLORREF value for the new color.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetColor, FNTYPE_THEME_SETPENCOLOR
*/
inline SURESULT Theme_SetPenColor(SUHANDLE hTheme, COLORREF clr)
{
SUARGSetColor arg;
arg.hObject = hTheme;
arg.clr = clr;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETPENCOLOR, &arg);
}
/** Gets a theme's fill color.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param clr is a pointer to a COLORREF value that will receive the
* current fill color.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetColor, FNTYPE_THEME_GETFILLCOLOR
*/
inline SURESULT Theme_GetFillColor(SUHANDLE hTheme, COLORREF *clr)
{
SUARGGetColor arg;
arg.hObject = hTheme;
arg.clr = clr;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETFILLCOLOR, &arg);
}
/** Sets a theme's fill color.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param clr is a COLORREF value for the new color.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetColor, FNTYPE_THEME_SETFILLCOLOR
*/
inline SURESULT Theme_SetFillColor(SUHANDLE hTheme, COLORREF clr)
{
SUARGSetColor arg;
arg.hObject = hTheme;
arg.clr = clr;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETFILLCOLOR, &arg);
}
/** Gets a theme's pen width.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param width is a pointer to a size_t value that will receive the current
* pen width.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_THEME_GETPENWIDTH
*/
inline SURESULT Theme_GetPenWidth(SUHANDLE hTheme, size_t *width)
{
SUARGGetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = width;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETPENWIDTH, &arg);
}
/** Sets a theme's pen width.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param width is a size_t value for the new pen width.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetUnsigned, FNTYPE_THEME_SETPENWIDTH
*/
inline SURESULT Theme_SetPenWidth(SUHANDLE hTheme, size_t width)
{
SUARGSetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = width;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETPENWIDTH, &arg);
}
/** Gets a theme's pen style.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param style is a pointer to a size_t value that will receive the current
* pen style.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, PENSTYLE, FNTYPE_THEME_GETPENSTYLE
*/
inline SURESULT Theme_GetPenStyle(SUHANDLE hTheme, size_t *style)
{
SUARGGetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = style;
return suapi.ShapeUp_Call(FNTYPE_THEME_GETPENSTYLE, &arg);
}
/** Sets a theme's pen style.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param style is a size_t value for the new pen style.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetUnsigned, PENSTYLE, FNTYPE_THEME_SETPENSTYLE
*/
inline SURESULT Theme_SetPenStyle(SUHANDLE hTheme, size_t style)
{
SUARGSetUnsigned arg;
arg.hObject = hTheme;
arg.unsignedval = style;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETPENSTYLE, &arg);
}
/** Sets a raster themes image data.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param hbm is a handle to a Windows bitmap. ShapeUp will
* take ownership of the bitmap and destroy it when its no
* longer needed.
* \param west is the western boudary of the raster.
* \param south is the southern boudary of the raster.
* \param east is the eastern boudary of the raster.
* \param north is the northern boudary of the raster.
* \param sourceHint is a description of where the data came from.
* E.g. if loaded from a file, this could be the file name.
* This parameter is informational only, and may be NULL.
* If supplied, it is displayed in the ShapeUp statistical view.
* \sa SUARGSetRasterImage, FNTYPE_THEME_SETRASTERIMAGE
*/
inline SURESULT Theme_SetRasterImage(SUHANDLE hTheme, HBITMAP hbm, double west, double south, double east, double north, const char *sourceHint)
{
SUARGSetRasterImage arg;
arg.hTheme = hTheme;
arg.hbm = hbm;
arg.west = west;
arg.south = south;
arg.east = east;
arg.north = north;
arg.sourceHint = sourceHint;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETRASTERIMAGE, &arg);
}
/** Sets data to be serialized with a theme. This function can be
* called at any time setting new data. However, when this function
* is called, any old data is discarded and fully replaced with the
* new.\n
* This data can later be restored from a ShapeUp workspace file
* when it is loaded, if the plug-in has set up a deserialize hook
* using the ShapeUp_AddDeserializeHook call.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param byteCount is the size of the \a bytes array.
* \param bytes is a pointer to a byte sequence containing the data to
* be serialized.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetSerialData, FNTYPE_WORKSPACE_SETSERIALDATA,
* ShapeUp_AddDeserializeHook()
*/
inline SURESULT Theme_SetSerialData(SUHANDLE hTheme, size_t byteCount, const void *bytes)
{
SUARGSetSerialData arg;
arg.hShapeUp = suapi.hShapeUp;
arg.hObject = hTheme;
arg.byteCount = byteCount;
arg.bytes = bytes;
return suapi.ShapeUp_Call(FNTYPE_THEME_SETSERIALDATA, &arg);
}
/** Clears the current shape selection in a theme.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_THEME_CLEARSELECTION
*/
inline SURESULT Theme_ClearSelection(SUHANDLE hTheme)
{
return suapi.ShapeUp_Call(FNTYPE_THEME_CLEARSELECTION, hTheme);
}
/** Selects a theme.
* \param hTheme is the \ref SUHANDLE to the theme.
* \param select is true if selecting and false if deselecting.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_THEME_SELECT
*/
inline SURESULT Theme_Select(SUHANDLE hTheme, bool select)
{
SUARGSetBOOL arg;
arg.hObject = hTheme;
arg.boolval = select;
return suapi.ShapeUp_Call(FNTYPE_THEME_SELECT, &arg);
}
/** Inverts the current selection in a theme.
* \param hTheme is the \ref SUHANDLE to the theme.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_THEME_INVERTSELECTION
*/
inline SURESULT Theme_InvertSelection(SUHANDLE hTheme)
{
return suapi.ShapeUp_Call(FNTYPE_THEME_INVERTSELECTION, hTheme);
}
/********************************************************************
* ShapeUp API, Shape functions implementations
*******************************************************************/
/** Determines if a shape is selected within a given theme.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param selected is a pointer to a BOOL that will receive the selected
* state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGIsShapeSelected, FNTYPE_SHAPE_ISSELECTED
*/
inline SURESULT Shape_IsSelected(SUHANDLE hShape, SUHANDLE hTheme, BOOL *selected)
{
SUARGIsShapeSelected arg;
arg.hShape = hShape;
arg.hTheme = hTheme;
arg.selected = selected;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_ISSELECTED, &arg);
}
/** Changes the selection state of a shape in a given theme.
* \param hShape is an \ref SUHANDLE to the shape to select.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param select is a BOOL that contains the new selection
* state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSelectShape, FNTYPE_SHAPE_SELECT
*/
inline SURESULT Shape_Select(SUHANDLE hShape, SUHANDLE hTheme, BOOL select)
{
SUARGSelectShape arg;
arg.hShape = hShape;
arg.hTheme = hTheme;
arg.select = select;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_SELECT, &arg);
}
/** Retrieves the type of this shape.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param type is a pointer to a ShapeType that will receive
* the shapes's type.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapeType, FNTYPE_SHAPE_GETSHAPETYPE,
*/
inline SURESULT Shape_GetShapeType(SUHANDLE hShape, ShapeType *type)
{
SUARGGetShapeType arg;
arg.hObject = hShape;
arg.type = type;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETSHAPETYPE, &arg);
}
/** Gets a shape's bounding box.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param xmin is a pointer to a double that will receive the west-most value.
* This parameter might be NULL if it's of no interest.
* \param ymin is a pointer to a double that will receive the south-most value.
* This parameter might be NULL if it's of no interest.
* \param xmax is a pointer to a double that will receive the east-most value.
* This parameter might be NULL if it's of no interest.
* \param ymax is a pointer to a double that will receive the north-most value.
* This parameter might be NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBounds, FNTYPE_SHAPE_GETBOUNDS
*/
inline SURESULT Shape_GetBounds(SUHANDLE hShape, double *xmin, double *ymin, double *xmax, double *ymax)
{
SUARGGetBounds arg;
arg.hObject = hShape;
arg.xmin = xmin;
arg.ymin = ymin;
arg.xmax = xmax;
arg.ymax = ymax;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETBOUNDS, &arg);
}
/** Gets the count of all parts in this shape.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param count is a pointer to an unsigned int that will receive the count value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_SHAPE_GETPARTCOUNT
*/
inline SURESULT Shape_GetPartCount(SUHANDLE hShape, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hShape;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETPARTCOUNT, &arg);
}
/** Gets the count of all parts in this shape.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param part is the zero based index of the part in this shape to query.
* \param count is a pointer to an unsigned int that will receive the count value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsignedByIndex, FNTYPE_SHAPE_GETCOORDINATECOUNT
*/
inline SURESULT Shape_GetCoordinateCount(SUHANDLE hShape, size_t part, size_t *count)
{
SUARGGetUnsignedByIndex arg;
arg.hObject = hShape;
arg.nIndex = part;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETCOORDINATECOUNT, &arg);
}
/** Gets the count of all parts in this shape.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param part is the zero based index of the part in this shape to query.
* \param coordIndex is zero based index of the coordinate in the specified part.
* \param x [out] is a pointer to an double that will receive the x value.
* This value can be set to NULL if it's of no interest.
* \param y [out] is a pointer to an double that will receive the y value.
* This value can be set to NULL if it's of no interest.
* \param z [out] is a pointer to an double that will receive the z value.
* This value can be set to NULL if it's of no interest.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetCoordinate, FNTYPE_SHAPE_GETCOORDINATE
*/
inline SURESULT Shape_GetCoordinate(SUHANDLE hShape, size_t part, size_t coordIndex, double *x, double *y, double *z)
{
SUARGGetCoordinate arg;
arg.hShape = hShape;
arg.nPart = part;
arg.nIndex = coordIndex;
arg.x = x;
arg.y = y;
arg.z = z;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETCOORDINATE, &arg);
}
/** Gets the coordinate of this shape closest to a reference point.
* \param hShape is the \ref SUHANDLE to the shape to query.
* \param refx [in] = reference point x value.
* \param refy [in] = reference point y value.
* \param closestx [out] = the coordinate on this shape closest to ref x value.
* \param closesty [out] = the coordinate on this shape closest to ref y value.
* \sa SUARGGetClosestPoint, FNTYPE_SHAPE_GETCLOSESTPOINT
*/
inline SURESULT Shape_GetClosestPoint(SUHANDLE hShape, double refx, double refy, double *closestx, double *closesty)
{
SUARGGetClosestPoint arg;
arg.hShape = hShape;
arg.refx = refx;
arg.refy = refy;
arg.closestx = closestx;
arg.closesty = closesty;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETCLOSESTPOINT, &arg);
}
/** Retrieves an attribute for a shape within a theme.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the text, then the actual text can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param column is the zero-based index of the attribute to query.
* \param buffer is a pointer to a character buffer that will receive the text.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetAttribute, FNTYPE_SHAPE_GETATTRIBUTE
*/
inline SURESULT Shape_GetAttribute(SUHANDLE hShape, SUHANDLE hTheme, size_t column, char *buffer, size_t *bufferSize)
{
SUARGGetAttribute arg;
arg.hShape = hShape;
arg.hTheme = hTheme;
arg.nCol = column;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETATTRIBUTE, &arg);
}
/** Sets an attribute value of a shape within a theme.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param column is the zero-based index of the attribute.
* \param data is a null-terminated string that contains the new value.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGSetAttribute, FNTYPE_SHAPE_SETATTRIBUTE
*/
inline SURESULT Shape_SetAttribute(SUHANDLE hShape, SUHANDLE hTheme, size_t column, const char *data)
{
SUARGSetAttribute arg;
arg.hShape = hShape;
arg.hTheme = hTheme;
arg.nCol = column;
arg.data = data;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_SETATTRIBUTE, &arg);
}
/** Sets multiple attribute values of a shape within a theme.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param count is the number of attribute values in \a data.
* \param data is an array of null-terminated strings that contains the new values.
* The \a data array may contain fewer attributes than the theme can handle.
* To avoid affecting an attribute value, set the appropriate field to NULL.
* To clear an attribute, set the field to an empty string, "".
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa Shape_SetAttribute(), SUARGSetAttributes, FNTYPE_SHAPE_SETATTRIBUTES
*/
inline SURESULT Shape_SetAttributes(SUHANDLE hShape, SUHANDLE hTheme, size_t count, const char *data[])
{
SUARGSetAttributes arg;
arg.hShape = hShape;
arg.hTheme = hTheme;
arg.count = count;
arg.data = data;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_SETATTRIBUTES, &arg);
}
/** Retrieves underlying shape byte buffer for a shape. The resulting \a buffer
* can be casted to pointer to a CShapeRecord.\n\n This function
* can be used in a two step process. First it's used to query ShapeUp for
* the buffer size needed to fit the data, then the actual data can be
* fetched.\n\n To query for the buffer size, set \a buffer to NULL, and let
* \a bufferSize point to a size_t that will receive the value. The size
* returned includes space for the null termination of the string. Allocate
* a proper character buffer and call the function again with this \a buffer
* and the returned \a bufferSize.
* \param hShape is an \ref SUHANDLE to the shape to query.
* \param buffer is a pointer to a byte buffer that will receive the data.
* \param bufferSize is a pointer to a size_t indicates the size of the \a buffer.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetShapeBytes, FNTYPE_SHAPE_GETSHAPEBYTES
*/
inline SURESULT Shape_GetShapeBytes(SUHANDLE hShape, unsigned char *buffer, size_t *bufferSize)
{
SUARGGetShapeBytes arg;
arg.hShape = hShape;
arg.buffer = buffer;
arg.bufferSize = bufferSize;
return suapi.ShapeUp_Call(FNTYPE_SHAPE_GETSHAPEBYTES, &arg);
}
/********************************************************************
* ShapeUp API, Recordset functions implementations
*******************************************************************/
/** Advances a ShapeUp recordset to the next item.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_RECORDSET_NEXT
*/
inline SURESULT Recordset_Next(SUHANDLE hRecordset)
{
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_NEXT, hRecordset);
}
/** Steps a ShapeUp recordset to the previous item.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_RECORDSET_PREV
*/
inline SURESULT Recordset_Prev(SUHANDLE hRecordset)
{
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_PREV, hRecordset);
}
/** Moves a ShapeUp recordset cursor to the first item.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_RECORDSET_FIRST
*/
inline SURESULT Recordset_First(SUHANDLE hRecordset)
{
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_FIRST, hRecordset);
}
/** Moves a ShapeUp recordset cursor to the last item.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_RECORDSET_LAST
*/
inline SURESULT Recordset_Last(SUHANDLE hRecordset)
{
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_LAST, hRecordset);
}
/** Get an element from a ShapeUp recordset at the current cursor
* position.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \param handle is a pointer to an \ref SUHANDLE that will receive
* a handle to an object defined in the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetHandle, FNTYPE_RECORDSET_GET
*/
inline SURESULT Recordset_Get(SUHANDLE hRecordset, SUHANDLE *handle)
{
SUARGGetHandle arg;
arg.hObject = hRecordset;
arg.hResult = handle;
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_GET, &arg);
}
/** Checks if the recordset cursor is moved past the last element.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \param eof is a pointer to a BOOL that will receive the
* end-of-file state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_RECORDSET_EOF
*/
inline SURESULT Recordset_Eof(SUHANDLE hRecordset, BOOL *eof)
{
SUARGGetBOOL arg;
arg.hObject = hRecordset;
arg.boolval = eof;
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_EOF, &arg);
}
/** Checks if the recordset cursor is moved before the first element.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \param bof is a pointer to a BOOL that will receive the
* beginning-of-file state.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetBOOL, FNTYPE_RECORDSET_BOF
*/
inline SURESULT Recordset_Bof(SUHANDLE hRecordset, BOOL *bof)
{
SUARGGetBOOL arg;
arg.hObject = hRecordset;
arg.boolval = bof;
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_BOF, &arg);
}
/** Closes a ShapeUp recordset. It is important to close all retrieved
* recordsets to avoid resource leaks.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa FNTYPE_RECORDSET_CLOSE
*/
inline SURESULT Recordset_Close(SUHANDLE hRecordset)
{
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_CLOSE, hRecordset);
}
/** Retrieves the number of item in a ShapeUp recordset.
* \param hRecordset is an \ref SUHANDLE to the recordset.
* \param count is a pointer to size_t that will receive the item
* count.
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa SUARGGetUnsigned, FNTYPE_RECORDSET_GETCOUNT
*/
inline SURESULT Recordset_GetCount(SUHANDLE hRecordset, size_t *count)
{
SUARGGetUnsigned arg;
arg.hObject = hRecordset;
arg.unsignedval = count;
return suapi.ShapeUp_Call(FNTYPE_RECORDSET_GETCOUNT, &arg);
}
#ifdef __cplusplus
/********************************************************************
* ShapeUp API, C++ classes
*******************************************************************/
/** \brief Representation of a integer based position or vector.
*/
class SUPoint
{
public:
/** Default constructor.
*/
SUPoint() {}
SUPoint(int _x, int _y) : x(_x), y(_y) {}
int x, y;
const SUPoint& operator+=(const SUPoint &p) { x -= p.x; y -= p.y; return *this; }
const SUPoint& operator-=(const SUPoint &p) { x -= p.x; y -= p.y; return *this; }
bool operator==(const SUPoint &rhs) const { return x == rhs.x && y == rhs.y; }
bool operator!=(const SUPoint &rhs) const { return !(*this == rhs); }
};
/** \brief Representation of a floating point double precision
* based position or vector.
*/
class SUPointf
{
public:
/** Default constructor.
*/
SUPointf() {}
SUPointf(double _x, double _y) : x(_x), y(_y) {}
double x, y;
const SUPointf& operator+=(const SUPointf &p) { x -= p.x; y -= p.y; return *this; }
const SUPointf& operator-=(const SUPointf &p) { x -= p.x; y -= p.y; return *this; }
bool operator==(const SUPointf &rhs) const { return x == rhs.x && y == rhs.y; }
bool operator!=(const SUPointf &rhs) const { return !(*this == rhs); }
};
/** \brief Representation of a integer based size in two dimensions.
*/
class SUSize
{
public:
SUSize() {}
SUSize(size_t w, size_t h) : width(w), height(h) {}
size_t width, height;
};
/** \brief Representation of a floating point double precision
* based size in two dimensions.
*/
class SUSizef
{
public:
SUSizef() {}
SUSizef(double w, double h) : width(w), height(h) {}
double width, height;
};
/** \brief Representation of a floating point double precision
* based axis-aligned rectangle.
*/
class SURectf
{
public:
/** Default constructor.
*/
SURectf() {}
SURectf(double _x1, double _y1, double _x2, double _y2) : x1(_x1), y1(_y1), x2(_x2), y2(_y2) {}
double x1, y1, x2, y2;
/** Arranges the rectangle to ensure x1 <= x2 and y1 <= y2.
*/
void Normalize()
{
if (x1 > x2)
std::swap(x1, x2);
if (y1 > y2)
std::swap(y1, y2);
}
/** Returns the width of this rectangle.
* \return The width of this rectangle which might be negative
* if not normalized.
*/
double Width() const
{
return x2 - x1;
}
/** Returns the height of this rectangle.
* \return The height of this rectangle which might be negative
* if not normalized.
*/
double Height() const
{
return y2 - y1;
}
/** Increases the size of the rectangle with two times s
* (each side once).
* \post The rectangle is normalized.
*/
void Inflate(const SUSizef& s)
{
Normalize();
x1 -= s.width;
x2 += s.width;
y1 -= s.height;
y2 += s.height;
}
/** Returns true if the point p is contained within the rectangle,
* otherwise false.
*/
bool Contains(const SUPointf& p)
{
return (p.x >= x1 && p.x <= x2 && p.y >= y1 && p.y <= y2);
}
/** Returns true if the point at coordinate (x, y) is contained
* within the rectangle, otherwise false.
*/
bool Contains(double x, double y) const
{
return (x >= x1 && x <= x2 && y >= y1 && y <= y2);
}
/** Returns true if the rectangle intersects the rectangle r,
* otherwise false.
*/
bool Intersects(const SURectf& r) const
{
if (Contains(r.x1, r.y1)) return true;
if (Contains(r.x1, r.y2)) return true;
if (Contains(r.x2, r.y2)) return true;
if (Contains(r.x2, r.y1)) return true;
if (r.Contains(x1, y1)) return true;
if (r.Contains(x1, y2)) return true;
if (r.Contains(x2, y2)) return true;
if (r.Contains(x2, y1)) return true;
if (min(x1, x2) < min(r.x1, r.x2) && max(x1, x2) > max(r.x1, r.x2))
{
if (min(y1, y2) > min(r.y1, r.y2) && max(y1, y2) < max(r.y1, r.y2))
return true;
}
else if (min(x1, x2) > min(r.x1, r.x2) && max(x1, x2) < max(r.x1, r.x2))
{
if (min(y1, y2) < min(r.y1, r.y2) && max(y1, y2) > max(r.y1, r.y2))
return true;
}
return false;
}
};
/** \brief Base class for ShapeUp object classes.
*
* SUObject manages the internal handle to the ShapeUp object.
*/
class SUObject
{
public:
/** Default constructor.
*/
SUObject() : _h(NULL) {};
/** Constructor.
* \param h is a handle to a ShapeUp object.
*/
SUObject(SUHANDLE h) : _h(h) {};
/** Virtual destructor.
*/
virtual ~SUObject() {};
/** Used for conversion to an SUHANDLE.
*/
operator SUHANDLE() { return _h; }
/** Checks if this object has a valid \ref SUHANDLE.
* \return true if valid, and false otherwise.
*/
virtual bool IsValid() const
{
if (_h == NULL)
return false;
BOOL valid;
ShapeUp_IsValidHandle(_h, &valid);
return (valid != FALSE);
}
protected:
SUHANDLE _h;
};
/** \brief A wrapper class for error return values.
*
* An SUException is thrown from the SU classes when an
* error code is returned from ShapeUp.
*/
class SUException
{
public:
/** Constructor.
* \param res is a SURESULT value from a ShapeUp call.
*/
SUException(SURESULT res) : _res(res) {};
/** Getter for the error code.
* \return The actual SURESULT.
*/
SURESULT GetErrorCode() const { return _res; }
/** Translates the underlying SURESULT into a human
* readable string.
* \return The error description.
*/
std::string GetErrorDesc() const
{
std::string d;
size_t bufSize;
ShapeUp_GetErrorDescription(_res, NULL, &bufSize);
char *buf = new char[bufSize];
ShapeUp_GetErrorDescription(_res, buf, &bufSize);
d = buf;
delete [] buf;
return d;
}
protected:
SURESULT _res;
};
/** \brief Handles a single ShapeUp menu item.
*
* An SUMenuItem object can be retreived from various sources, e.g.
* ShapeUp_AddNewLayerHook() returns a handle to a menu item.
* \sa ShapeUp_AddNewLayerHook()
*/
class SUMenuItem : public SUObject
{
public:
/** Default constructor.
*/
SUMenuItem() {}
/** Constructor.
* \param hMenuItem is a handle to a menu item.
*/
SUMenuItem(SUHANDLE hMenuItem) : SUObject(hMenuItem) {}
/** Changes the availability of the menu item.
* \param bEnable = true enables the item, false disables.
*/
void SetEnabled(bool bEnable)
{
SURESULT res = MenuItem_SetEnabled(_h, bEnable);
if (res != SURESULT_OK)
throw SUException(res);
}
};
/** \example example_sutoolbar.cpp
* This is an example of how to use the SUToolBar class.
* It assumes there is a toolbar resource named IDR_TOOLBAR, with
* two buttons, ID_LOAD_TBBUTTON and ID_SAVE_TBBUTTON.
*/
/** \brief Handles a plug-in defined toolbar.
*
* An SUToolBar object should be created by the plug-in if
* it wants to supply an extra toolbar. A plug-in can have
* more than one toolbar if necessary.
* ShapeUp does not currently expose its own toolbars.
*
* To get toolbar button notifications, the ShapeUp_AddToolBarButtonHook()
* must have been called, and the plug-in hook function, set in fnInit(),
* must handle HOOKTYPE_TOOLBARBUTTON notifications.
*/
class SUToolBar : public SUObject
{
public:
/** Default constructor.
*/
SUToolBar() {}
/** Creates a new ShapeUp toolbar.
* \param hInstance = handle to the module containing the toolbar resource.
* \param lpszResourceName = name of the toolbar resource.
* \param name = name of the toolbar used in ShapeUp. (Displayed to users)
*/
void Create(HINSTANCE hInstance, LPCTSTR lpszResourceName, const char *name)
{
SURESULT res = ToolBar_Create(hInstance, lpszResourceName, name, &_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Creates a new ShapeUp toolbar.
* \param hInstance = handle to the module containing the toolbar resource.
* \param nID = id of the toolbar resource.
* \param name = name of the toolbar used in ShapeUp. (Displayed to users)
*/
void Create(HINSTANCE hInstance, UINT nID, const char *name)
{
Create(hInstance, MAKEINTRESOURCE(nID), name);
}
/** Checks if this toolbar is visible or not.
* \return true if the toolbar is visible, and false otherwise.
* \sa ToolBar_IsVisible()
*/
bool IsVisible()
{
BOOL b;
SURESULT res = ToolBar_IsVisible(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return (b != 0);
}
/** Retrieves the number of buttons in this toolbar.
* \return The button count.
* \sa ToolBar_GetButtonCount()
*/
size_t GetButtonCount()
{
size_t c;
SURESULT res = ToolBar_GetButtonCount(_h, &c);
if (res != SURESULT_OK)
throw SUException(res);
return c;
}
/** Enables or disables a button in this toolbar.
* \param nID = id of the toolbar button defined in the toolbar resource.
* \param bEnable = true enables and false disables the button.
* \sa ToolBar_SetButtonEnabled()
*/
void SetButtonEnabled(UINT nID, bool bEnable)
{
SURESULT res = ToolBar_SetButtonEnabled(_h, nID, bEnable);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Checks or unchecks a button in this toolbar.
* \param nID = id of the toolbar button defined in the toolbar resource.
* \param bChecked = true checks and false unchecks the button.
* \sa ToolBar_SetButtonChecked()
*/
void SetButtonChecked(UINT nID, bool bChecked)
{
SURESULT res = ToolBar_SetButtonChecked(_h, nID, bChecked);
if (res != SURESULT_OK)
throw SUException(res);
}
};
/** \brief Represents the ShapeUp status bar.
*
* The ShapeUp statusbar can be accessed from a GPI, allowing
* it to allocate a dedicated statusbar pane for displaying status
* information, or to use the progress bar that is used by ShapeUp
* internal functions.
*/
class SUStatusBar
{
public:
/** Default constructor.
*/
SUStatusBar() : _hProgress(NULL) {}
/** Sets the information in a pane previously allocated by a call to
* AllocatePane(). A pane can have a text, an icon or both.
* \param text is the new text string. NULL clears the
* field, and displays the 'Ready' message.
* \sa ShapeUp_SetStatusBarText()
*/
void SetText(const char *text)
{
SURESULT res = ShapeUp_SetStatusBarText(text);
if (res != SURESULT_OK)
throw SUException(res);
}
/** This function will prepare the progress bar in ShapeUp's statusbar.
* Any call to BeginProgress() must have a matching call to EndProgress().
* \param title = Optional progress bar title which, if supplied, will be
* dispayed to the left och the progress bar. A null value means no title,
* which is default.
* \param progress = Optional initial progress where 0.0f <= progress <= 1.0f.
* Default is 0.
* \sa ShapeUp_BeginProgress()
*/
void BeginProgress(const char *title = NULL, float progress = 0.f)
{
SURESULT res = ShapeUp_BeginProgress(title, progress, &_hProgress);
if (res != SURESULT_OK)
throw SUException(res);
}
/** This function will prepare the progress bar in ShapeUp's statusbar.
* Any call to BeginProgress() must have a matching call to EndProgress().
* \param progress = initial progress where 0.0f <= progress <= 1.0f.
* \sa ShapeUp_SetProgress()
*/
void SetProgress(float progress)
{
SURESULT res = ShapeUp_SetProgress(_hProgress, progress);
if (res != SURESULT_OK)
throw SUException(res);
}
/** This function will close the progress bar in ShapeUp's statusbar.
* Any call to BeginProgress() must have a matching call to EndProgress().
* \sa ShapeUp_EndProgress()
*/
void EndProgress()
{
SURESULT res = ShapeUp_EndProgress(_hProgress);
if (res != SURESULT_OK)
throw SUException(res);
_hProgress = NULL;
}
/** This function will allocate a pane in ShapeUp's statusbar. The GPI will
* have exclusive access to this pane. A status bar pane can contain text,
* an icon or both. Since there is only a limited space
* make sure it's used for something valuable, or that it's lifetime is short.
* A GPI may allocate more than one pane.
* \param width = desired width of the pane in pixels.
* \return The pane index if successful.
* \sa ReleasePane(), ShapeUp_AllocateStatusBarPane()
*/
size_t AllocatePane(size_t width)
{
SUHANDLE h;
SURESULT res = ShapeUp_AllocateStatusBarPane(width, &h);
if (res != SURESULT_OK)
throw SUException(res);
_paneHandles.push_back(h);
return _paneHandles.size()-1;
}
/** This function will release a pane previously allocated by a call to
* AllocatePane().
* \param paneIndex = the index of the pane to release.
* \sa ReleasePane(), ShapeUp_ReleaseStatusBarPane()
*/
void ReleasePane(size_t paneIndex)
{
if (paneIndex >= _paneHandles.size())
throw SUException(SURESULT_E_INDEXOUTOFBOUNDS);
SURESULT res = ShapeUp_ReleaseStatusBarPane(_paneHandles[paneIndex]);
if (res != SURESULT_OK)
throw SUException(res);
_paneHandles.erase(_paneHandles.begin() + paneIndex);
}
/** Retrieves the number of panes this SUStatusBar has allocated.
* \return The number of panes.
*/
size_t GetPaneCount()
{
return _paneHandles.size();
}
/** Sets the information in a pane previously allocated by a call to
* AllocatePane(). A pane can have a text, an icon or both.
* \param paneIndex = the index of the pane to release.
* \param text = text to be displayed in the pane. Null clears the
* text.
* \param hIcon = handle to an icon to be displayed in the pane. Null
* clears the icon.
* \sa AllocatePane(), ShapeUp_SetStatusBarPaneInfo()
*/
void SetPaneInfo(size_t paneIndex, const char *text, HICON hIcon)
{
if (paneIndex >= _paneHandles.size())
throw SUException(SURESULT_E_INDEXOUTOFBOUNDS);
SURESULT res = ShapeUp_SetStatusBarPaneInfo(_paneHandles[paneIndex], text, hIcon, NULL);
if (res != SURESULT_OK)
throw SUException(res);
}
protected:
std::vector _paneHandles;
SUHANDLE _hProgress;
};
/** \brief Multi-purpose recordset class.
*
* An SURecordset object can be retreived from various sources, e.g.
* SUWorkspace::GetSelectedThemes() and SUTheme::GetShapesInRect().
* Depending on the source, the recordset contains handles to different
* objects. However, one recordset always manages handles to the same
* object type.
*
* Once a recordset is opened, it must be closed with a call to
* Close().
*/
class SURecordset : public SUObject
{
public:
/** Default constructor.
*/
SURecordset() {}
/** Constructor.
* \param hRecordset is a handle to a ShapeUp recordset.
*/
SURecordset(SUHANDLE hRecordset) : SUObject(hRecordset) {}
/** Advances the recordset cursor to the next record.
*/
void Next()
{
SURESULT res = Recordset_Next(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Backs the recordset cursor to the previous record.
*/
void Prev()
{
SURESULT res = Recordset_Prev(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets the recordset cursor to the first record.
*/
void First()
{
SURESULT res = Recordset_First(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets the recordset cursor to the last record.
*/
void Last()
{
SURESULT res = Recordset_Last(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Retreives the element at the recordset cursor.
* The object return type depends on the source of
* the recordset. It is safe to store a handle to
* an object for later use while traversing the recordset.
* \return A handle to the ShapeUp object.
*/
SUHANDLE Get()
{
SUHANDLE h;
SURESULT res = Recordset_Get(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return h;
}
/** Checks if the recordset cursor is advanced beyond
* the last record.
* \return true if the recordset cursor is advanced beyond
* the last record, otherwise false.
*/
bool Eof()
{
BOOL b;
SURESULT res = Recordset_Eof(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return (b != 0);
}
/** Checks if the recordset cursor is pointing before
* the first record.
* \return true if the recordset cursor is pointing before
* the last record, otherwise false.
*/
bool Bof()
{
BOOL b;
SURESULT res = Recordset_Bof(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return (b != 0);
}
/** Closes the recordset, and frees internal resources.
*
* IMPORTANT: All recordsets must be closed to avoid memory leaks.
*/
void Close()
{
SURESULT res = Recordset_Close(_h);
if (res != SURESULT_OK)
throw SUException(res);
_h = NULL;
}
/** Gets the number of records in the recordset.
* \return The number of records in the recordset.
*/
size_t GetCount()
{
size_t c;
SURESULT res = Recordset_GetCount(_h, &c);
if (res != SURESULT_OK)
throw SUException(res);
return c;
}
};
/** \example example_sudatapage.cpp
* This is an example of how to add custom data pages in ShapeUp. In this particular
* example, a page containing a singe tree control is created and populated with
* some dummy data.
*/
/** \brief Handles custom data pages in ShapeUp.
*
* One or more custom data pages can be added to any workspace. A data page can
* contain any windows child control. E.g list controls, tree controls or
* any combination of controls placed on a parent control.\n
*
* \image html img_datapage.png "A Custom Data Page"
*/
class SUDataPage : public SUObject
{
public:
/** Default constructor.
*/
SUDataPage() {}
/** Constructor.
* \param hDataPage = handle to a ShapeUp data page object.
* \sa SUWorkspace::AddDataPage()
*/
SUDataPage(SUHANDLE hDataPage) : SUObject(hDataPage) {}
/** Removes this data page from the workspace it's attached to.
* If the child window is still attached to this data page,
* it will be destroyed.
* \sa DataPage_Remove(), Workspace_AddDataPage()
*/
void Remove()
{
SURESULT res = DataPage_Remove(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets access to the ShapeUp data page window.
* \return Returns the windows handle to the data page window.
* \sa DataPage_GetHWND()
*/
HWND GetHWND()
{
HWND hwnd;
SURESULT res = DataPage_GetHWND(_h, &hwnd);
if (res != SURESULT_OK)
throw SUException(res);
return hwnd;
}
};
/** \example example_jscallfunction.js
* This is an example of a JavaScript in ShapeUp that is intended to be run
* by a GPI plugin using the SUJavaScript::CallFunction() method with
* 'doSomething' as argument. Note that since a call to init() is made at file
* level, the init() function will be called the first time SUJavaScript::CallFunction()
* is called. To avoid this behaviour, remove the call to init at file level at line 16.
*/
/** \brief Handles JavaScripts in ShapeUp.
*
* An SUJavaScript object can be loaded using SUWorkspace::LoadJavaScript().
* This script can then be executed via Run(), or a single function in the
* script may be called.\n
* Note: When creating a JavaScript, ShapeUp will have to run it once to
* instanciate the function objects. This will have the side effect that any
* code at file level will be executed the first time the CallFunction()
* method is called, after which the desired function is called. You can either
* avoid this by not having any code at file level, or make use of it as an
* initialisation method. See the following example:
* \include example_jscallfunction.js
*/
class SUJavaScript : public SUObject
{
public:
/** Default constructor.
*/
SUJavaScript() {}
/** Constructor.
* \param hJavaScript = handle to a ShapeUp JavaScript.
* \sa SUWorkspace::LoadJavaScript(), Workspace_LoadJavaScript()
*/
SUJavaScript(SUHANDLE hJavaScript) : SUObject(hJavaScript) {}
/** Executes a loaded JavaScript.
* \sa JavaScript_Run(), SUWorkspace::LoadJavaScript(), Workspace_LoadJavaScript()
*/
void Run()
{
SURESULT res = JavaScript_Run(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Executes a named function in a loaded JavaScript.
* \todo There is currently no support for passing arguments to the function
* back and forth.
*
* \param func_name = name of the function to execute.
* \sa JavaScript_CallFunction(), SUWorkspace::LoadJavaScript(), Workspace_LoadJavaScript()
*/
void CallFunction(const char *func_name)
{
SURESULT res = JavaScript_CallFunction(_h, func_name);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Closes a loaded JavaScript.
* \sa JavaScript_Close(), SUWorkspace::LoadJavaScript(), Workspace_LoadJavaScript()
*/
void Close()
{
SURESULT res = JavaScript_Close(_h);
if (res != SURESULT_OK)
throw SUException(res);
_h = NULL;
}
};
/** \brief Represents the ShapeUp map window.
*
* Each ShapeUp workspace contains a ShapeUp map window. This
* window may be used to overlay graphics, or change the view
* of the graphics within it.
*
* The ShapeUp map also maintaines an interaction state, \ref MAPSTATE, which
* controls the behaviour of the map presented to the user.
*/
class SUMap : public SUObject
{
public:
/** Constructor.
* \param hMap = handle to a ShapeUp map window.
* \sa SUWorkspace::GetMapWindow(), Workspace_GetMapWindow()
*/
SUMap(SUHANDLE hMap) : SUObject(hMap) {}
/** Retrieves the geographical bounds of the map window.
* \param r = a SURectf that will receive the bounds.
* \sa Map_GetBounds()
*/
void GetBounds(SURectf &r)
{
SURESULT res = Map_GetBounds(_h, &r.x1, &r.y1, &r.x2, &r.y2);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Retrieves the view size in device units of the map window.
* \param s = a SUSize that will receive the size.
* \sa Map_GetViewSize()
*/
void GetViewSize(SUSize &s)
{
SURESULT res = Map_GetViewSize(_h, &s.width, &s.height);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Converts geographical points, GP, to device points, DP.
* \param p = a SUPointf containing the geographical points.
* \param pt = a SUPoint that will receive the device points.
* \sa Map_GetViewSize()
*/
void GPtoDP(const SUPointf& p, SUPoint &pt)
{
SURESULT res = Map_GPtoDP(_h, p.x, p.y, &pt.x, &pt.y);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Converts device points, DP, to geographical points, GP.
* \param p = a SUPoint containing the device points.
* \param pt = a SUPointf that will receive the geographical points.
* \sa Map_GetViewSize()
*/
void DPtoGP(const SUPoint& p, SUPointf &pt)
{
SURESULT res = Map_DPtoGP(_h, p.x, p.y, &pt.x, &pt.y);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets access to the ShapeUp map window.
* \return Returns the windows handle to the map window.
* \sa Map_GetHWND()
*/
HWND GetHWND()
{
HWND h;
SURESULT res = Map_GetHWND(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return h;
}
/** Forces the map window to repaint itself. The map is rendered in
* two steps. First all map objects are drawn to a background buffer.
* Then that buffer is painted on the map, and on top of that,
* temporary objects are drawn. Temporary objects are rubber
* rectangles, bookmark icons, shapes being drawn, etc.
* \param bFullRedraw if true, all map objects are redrawn, and if
* false, the background buffer is used to paint the map objects
* and only the top items are redrawn.
* \sa Map_Repaint()
*/
void Repaint(bool bFullRedraw)
{
SURESULT res = Map_Repaint(_h, bFullRedraw);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Paints the current map to a dc.
* \sa Map_Draw()
*/
void Draw(HDC hdc, const SUSize &imagesize, const SUPointf ¢er, double geoWidth = 0., double geoHeight = 0.)
{
SURESULT res = Map_Draw(_h, hdc, imagesize.width, imagesize.height, center.x, center.y, geoWidth, geoHeight);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Centers the map.
* \param pt is the new center point.
* \sa Map_GetViewSize()
*/
void CenterMap(const SUPointf &pt)
{
SURESULT res = Map_CenterMap(_h, pt.x, pt.y);
}
/** Centers the map.
* \param x is the new center point east-west component.
* \param y is the new center point north-south component.
* \sa Map_GetViewSize()
*/
void CenterMap(double x, double y)
{
SURESULT res = Map_CenterMap(_h, x, y);
}
/** Zooms the map.
* \param factor is the factor used to zoom the map. 0.0 < factor < 1.0 zooms in,
* and 1.0 < factor zooms out.
* \sa Map_Zoom()
*/
void Zoom(double factor)
{
SURESULT res = Map_Zoom(_h, factor);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Zooms the map to the extent of selected shapes in a layer.
* \param hTheme is a handle to a ShapeUp theme, or a SUTheme object,
* in which to find selected ojects.
* \sa Map_Zoom()
*/
void ZoomToSelection(SUHANDLE hTheme)
{
SURESULT res = Map_ZoomToSelection(_h, hTheme);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Zooms the map to the extent of a layer.
* \param hTheme is a handle to a ShapeUp theme, or a SUTheme object.
* \sa Map_ZoomToExtent()
*/
void ZoomToExtent(SUHANDLE hTheme)
{
SURESULT res = Map_ZoomToExtent(_h, hTheme);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Returns the current map interaction state. The interaction state
* is a value indicating what the user is about to do, or is doing,
* in the map. This is in short the state of the mutual exclusive
* toolbar buttons like select, rectangle select, circle select, etc.
* This can be used to add new states to the map.
* \return A ShapeUp map interaction state.
* \sa SetInteractionState(), Map_GetInteractionState(), \ref MAPSTATE
*/
unsigned long GetInteractionState()
{
unsigned long ul;
SURESULT res = Map_GetInteractionState(_h, &ul);
if (res != SURESULT_OK)
throw SUException(res);
return ul;
}
/** Sets a new map interaction state. The interaction state
* is a value indicating what the user is about to do, or is doing,
* in the map. This is in short the state of the mutual exclusive
* toolbar buttons like select, rectangle select, circle select, etc.
* This can be used to add new states to the map.
* \param state is the new state. It must be one of the defined map
* interaction states. Note: Not all map states defined can be set.
* Check \ref MAPSTATE for more info.
* \sa GetInteractionState(), Map_SetInteractionState(), \ref MAPSTATE
*/
void SetInteractionState(unsigned long state)
{
SURESULT res = Map_SetInteractionState(_h, state);
if (res != SURESULT_OK)
throw SUException(res);
}
};
class SUTheme;
/** \brief Handles a shape object in ShapeUp.
*
* The SUShape class represents a shape object in ShapeUp. A shape can be
* a point, polyline or a polygon.
*/
class SUShape : public SUObject
{
public:
/** Default constructor.
*/
SUShape() {}
/** Constructor.
* \param hShape = handle to a ShapeUp shape.
* \sa SUTheme::GetShape(), Theme_GetShape()
*/
SUShape(SUHANDLE hShape) : SUObject(hShape) {}
/** Checks whether a shape is selected or not.
* \param hTheme = handle to a ShapeUp theme, or a SUTheme object,
* in which to find this object. Note: A shape can be contained in
* more than one theme under certain circumstances.
* \return true if the shape is selected in the theme hTheme, and
* false otherwise.
* \sa SUTheme, Shape_IsSelected()
*/
bool IsSelected(SUHANDLE hTheme) const
{
BOOL b;
SURESULT res = Shape_IsSelected(_h, hTheme, &b);
if (res != SURESULT_OK)
throw SUException(res);
return b != 0;
}
/** Selects or deselects the shape object.
* \param hTheme = handle to a ShapeUp theme, or a SUTheme object,
* in which to find this object. Note: A shape can be contained in
* more than one theme under certain circumstances.
* \param bSelect = if true, the shape will be selected, else deselected.
* \sa SUTheme, Shape_Select()
*/
void Select(SUHANDLE hTheme, bool bSelect)
{
SURESULT res = Shape_Select(_h, hTheme, bSelect);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the shape type of this shape.
* \return the ShapeType value of this shape.
* \sa Shape_GetShapeType()
*/
ShapeType GetShapeType() const
{
ShapeType type;
SURESULT res = Shape_GetShapeType(_h, &type);
if (res != SURESULT_OK)
throw SUException(res);
return type;
}
/** Gets the shapes bounding box.
* \param r [out] = a rectangle that will receive the shape bounds.
* \sa Shape_GetBounds()
*/
void GetBounds(SURectf &r) const
{
SURESULT res = Shape_GetBounds(_h, &r.x1, &r.y1, &r.x2, &r.y2);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the count of all parts in this shape.
* \return the number of parts in this shape.
* \sa Shape_GetPartCount()
*/
size_t GetPartCount() const
{
size_t n;
SURESULT res = Shape_GetPartCount(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Gets the count of all coordinates in a part for this shape.
* \param part [in] = zero based index of the part to query.
* \return the number of coordinates for the given part.
* \sa Shape_GetCoordinateCount()
*/
size_t GetCoordinateCount(size_t part) const
{
size_t n;
SURESULT res = Shape_GetCoordinateCount(_h, part, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Gets a coordinate from this shape.
* \param part [in] = zero based index of the part to query.
* \param coordIndex [in] = zero based index of the coordinate of the part to query.
* \param coord [out] = the coordinate at the specified index.
* \sa Shape_GetCoordinate()
*/
void GetCoordinate(size_t part, size_t coordIndex, SUPointf &coord) const
{
SURESULT res = Shape_GetCoordinate(_h, part, coordIndex, &coord.x, &coord.y, NULL);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the coordinate of this shape closest to a reference point.
* \param ref [in] = reference point.
* \param closest [out] = the coordinate on this shape closest to \a ref.
* \sa Shape_GetClosestPoint()
*/
void GetClosestPoint(const SUPointf &ref, SUPointf &closest) const
{
SURESULT res = Shape_GetClosestPoint(_h, ref.x, ref.y, &closest.x, &closest.y);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries this shape for one of its attributes.
* \param hTheme = handle to a ShapeUp theme, or a SUTheme object,
* in which to find this object. Note: A shape can be contained in
* more than one theme under certain circumstances.
* \param index = zero-based index of the attribute column to query.
* \return an attribute value of this shape.
* \sa SUTheme, Shape_GetAttribute()
*/
std::string GetAttribute(SUHANDLE hTheme, size_t index) const
{
size_t bufSize = 0;
SURESULT res = Shape_GetAttribute(_h, hTheme, index, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Shape_GetAttribute(_h, hTheme, index, buf, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
std::string s(buf);
delete [] buf;
return s;
}
/** Sets an attribute for this shape.
* \param hTheme = handle to a ShapeUp theme, or a SUTheme object,
* in which to find this object. Note: A shape can be contained in
* more than one theme under certain circumstances.
* \param index = zero-based index of the attribute column to set.
* \param data = null-terminated string containing the attribute data.
* \sa SUTheme, Shape_SetAttribute()
*/
void SetAttribute(SUHANDLE hTheme, size_t index, const char* data)
{
SURESULT res = Shape_SetAttribute(_h, hTheme, index, data);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets multiple attribute values of a shape within a theme.
* \param hTheme is an \ref SUHANDLE to the theme containing the shape.
* \param count is the number of attribute values in \a data.
* \param data is an array of null-terminated strings that contains the new values.
* The \a data array may contain fewer attributes than the theme can handle.
* To avoid affecting an attribute value, set the appropriate field to NULL.
* To clear an attribute, set the field to an empty string, "".
* \return This function returns the \ref SURESULT value that ShapeUp
* returns from the SUExport::ShapeUp_Call() function.
* \sa Shape_SetAttributes(), SetAttribute()
*/
void SetAttributes(SUHANDLE hTheme, size_t count, const char *data[])
{
SURESULT res = Shape_SetAttributes(_h, hTheme, count, data);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries this shape for how many bytes are required to store the
* underlying binary shape object.
* \return The number of bytes required to store the binary shape object.
* \sa Shape_GetShapeBytes()
*/
size_t GetShapeSizeBytes() const
{
size_t n;
SURESULT res = Shape_GetShapeBytes(_h, NULL, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Retrieves the underlying binary shape object.
* \param buffer = a byte buffer larege enough to store the binary shape
* object. To get the size needed, first query the shape using the
* GetShapeSizeBytes() method.
* \param bufferSize = the size in bytes of buffer.
* \sa GetShapeSizeBytes(), Shape_GetShapeBytes()
*/
void GetShapeBytes(unsigned char *buffer, size_t bufferSize) const
{
SURESULT res = Shape_GetShapeBytes(_h, buffer, &bufferSize);
if (res != SURESULT_OK)
throw SUException(res);
}
};
/** \brief Represents a ShapeUp theme or layer.
*
* A ShapeUp theme manages raster images or vector objects and
* their attributes. Data can be added, manipulated or removed.
*
* Even though ShapeUp supports different types of vector data,
* such as points, lines and polygons, a single theme may currently
* not contain more than one type.
*
* An SUTheme is normally retrieved from an SUWorkspace object.
*/
class SUTheme : public SUObject
{
public:
/** Default constructor.
*/
SUTheme() {}
/** Constructor.
* \param hTheme is a handle to a ShapeUp theme.
* \sa SUWorkspace::GetTheme(), Workspace_GetTheme()
*/
SUTheme(SUHANDLE hTheme) : SUObject(hTheme) {}
/** Adds a new shape to this theme. Adding a shape updates the themes
* bounding box automatically.
* \param shapeData is the shape to be added. ShapeUp makes a copy of this shape.
* \return Returns a handle to the created shape.
* \sa Theme_AddShape(), BatchAddShapeBegin(), BatchAddShapeEnd()
*/
SUShape AddShape(const CShapeRecord *shapeData)
{
SUHANDLE h;
SURESULT res = Theme_AddShape(_h, shapeData, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUShape(h);
}
/** Turns off indexing and other time consuming tasks when calling AddShape().
* Use this if many shapes should be added at once. After the
* shapes have been added, call BatchAddShapeEnd() to turn the
* features back on again.
* \sa AddShape(), BatchAddShapeEnd(), Theme_BatchAddShapeBegin()
*/
void BatchAddShapeBegin()
{
SURESULT res = Theme_BatchAddShapeBegin(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Turns on indexing and other tasks after calling AddShape().
* \sa AddShape(), BatchAddShapeBegin(), Theme_BatchAddShapeEnd()
*/
void BatchAddShapeEnd()
{
SURESULT res = Theme_BatchAddShapeEnd(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Replaces a shape in this theme. After this operation, the handle hShape is
* still valid, but points to the new shape instead. Also, after a call to
* this function, the themes bounding box must be updated via a call to
* SUTheme::RecalcBounds()
* \param hShape is a handle to the shape to replace.
* \param shapeData is the shape to be inserted. ShapeUp makes a copy of this shape.
* \sa Theme_ReplaceShapeData(), SUTheme::RecalcBounds()
*/
void ReplaceShapeData(SUHANDLE hShape, const CShapeRecord *shapeData)
{
SURESULT res = Theme_ReplaceShapeData(_h, hShape, shapeData);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Deletes a shape in this theme. After this operation, the handle hShape is
* invalid. Also, after a call to this function, the themes bounding box
* must be updated via a call to SUTheme::RecalcBounds()
* \param hShape is a handle to the shape to delete.
* \sa Theme_DeleteShape()
*/
void DeleteShape(SUHANDLE hShape)
{
SURESULT res = Theme_DeleteShape(_h, hShape);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries ShapeUp if this theme is selected or not.
* \return True if this theme is selected, and false otherwise.
* \sa Theme_IsSelected()
*/
bool IsSelected()
{
BOOL b;
SURESULT res = Theme_IsSelected(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return b != 0;
}
/** Queries ShapeUp if this theme is read-only or not.
* \return True if this theme is read-only, and false otherwise.
* \sa Theme_IsReadOnly()
*/
bool IsReadOnly()
{
BOOL b;
SURESULT res = Theme_IsReadOnly(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return b != 0;
}
/** Queries ShapeUp if this theme is visible or not.
* \return True if this theme is visible, and false otherwise.
* \sa Theme_IsReadOnly()
*/
bool IsVisible()
{
BOOL b;
SURESULT res = Theme_IsVisible(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return b != 0;
}
/** Queries ShapeUp for the name of this theme.
* \return The name of this theme.
* \sa Theme_GetName()
*/
std::string GetName()
{
size_t bufSize = 0;
SURESULT res = Theme_GetName(_h, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Theme_GetName(_h, buf, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
std::string s(buf);
delete [] buf;
return s;
}
/** Sets a new name for this theme.
* \param name is a null-terminated string containing the new name for this theme.
* \sa Theme_SetName()
*/
void SetName(const char* name)
{
SURESULT res = Theme_SetName(_h, name);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries ShapeUp for the number of attributes this theme has.
* \return The number of attributes.
* \sa Theme_GetAttributeCount()
*/
size_t GetAttributeCount()
{
size_t n;
SURESULT res = Theme_GetAttributeCount(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Queries ShapeUp for the name of this themes attributes.
* \param column is the zero-based index of the attribute.
* \return The name of attribute at index column.
* \sa Theme_GetAttributeName()
*/
std::string GetAttributeName(size_t column)
{
size_t bufSize = 0;
SURESULT res = Theme_GetAttributeName(_h, column, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Theme_GetAttributeName(_h, column, buf, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
std::string s(buf);
delete [] buf;
return s;
}
/** Queries ShapeUp for the type of this themes attributes.
* \param column is the zero-based index of the attribute.
* \return The attribute type of attribute at index column.
* \sa \ref ATTRIBUTETYPE, Theme_GetAttributeType()
*/
unsigned long GetAttributeType(size_t column)
{
unsigned long type;
SURESULT res = Theme_GetAttributeType(_h, column, &type);
if (res != SURESULT_OK)
throw SUException(res);
return type;
}
/** Queries ShapeUp for the index of a named attribute in this theme.
* \param name is the name of the attribute to look up.
* \return The index of the named attribute. Throws an exception if
* the look-up failed.
* \sa \ref ATTRIBUTETYPE, Theme_GetAttributeIndex()
*/
size_t GetAttributeIndex(const char* name)
{
size_t index;
SURESULT res = Theme_GetAttributeIndex(_h, name, &index);
if (res != SURESULT_OK)
throw SUException(res);
return index;
}
/** Queries ShapeUp for the number of shapes this theme has.
* \return The number of shapes in this theme.
* \sa Theme_GetShapeCount()
*/
size_t GetShapeCount()
{
size_t n;
SURESULT res = Theme_GetShapeCount(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Queries ShapeUp for a shape of this theme.
* \param index is the zero-based index of the shape in this theme.
* \return The SUShape object at the given index.
* \sa Theme_GetShape()
*/
SUShape GetShape(size_t index)
{
SUHANDLE h;
SURESULT res = Theme_GetShape(_h, index, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUShape(h);
}
/** Queries ShapeUp for a shape of this theme.
* \param index is the shape index of the shape in this theme.
* \return The SUShape object with the given index.
* \sa Theme_GetShape()
*/
SUShape GetShapeFromIndex(size_t index)
{
SUHANDLE h;
SURESULT res = Theme_GetShapeFromIndex(_h, index, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUShape(h);
}
/** Queries ShapeUp for the shape type of this theme.
* \return The ShapeType of this theme.
* \sa Theme_GetShapeType()
*/
ShapeType GetShapeType()
{
ShapeType n;
SURESULT res = Theme_GetShapeType(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Gets the layers bounding box.
* \param r [out] is a rectangle that will receive the shape bounds.
* \sa Theme_GetBounds()
*/
void GetBounds(SURectf &r)
{
SURESULT res = Theme_GetBounds(_h, &r.x1, &r.y1, &r.x2, &r.y2);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Call this function to recalculate the layers bounding box after
* its data has been manipulated.
* \sa SUTheme::ReplaceShapeData()
*/
void RecalcBounds()
{
SURESULT res = Theme_RecalcBounds(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries ShapeUp for the shapes in this theme that intersects the
* \a shape argument. If the \a shape argument is taken from this theme,
* it is excluded from the resulting recordset.
* It's important to close the resulting recordset using SURecordset::Close()
* to avoid resource leaks.
* \param shape is a shape to compare this theme's shapes to to find
* intersections.
* \return A recordset containing shapes.
* \sa SURecordset, Theme_GetIntersectingShapes()
*/
SURecordset GetIntersectingShapes(SUShape shape)
{
SUHANDLE h;
SURESULT res = Theme_GetIntersectingShapes(_h, shape, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Queries ShapeUp for the shapes in a given rectangle in this theme.
* It's important to close the resulting recordset using SURecordset::Close()
* to avoid resource leaks.
* \param r is a rectangle to compare this theme's shapes to to find
* intersections.
* \param bPartiallyInRectOk if true, this function returns shapes
* intersecting the rectangle \a r. If false, only shapes fully
* contained in the rectangle \a r is returned.
* \return A recordset containing shapes.
* \sa SURecordset, Theme_GetShapesInRect()
*/
SURecordset GetShapesInRect(const SURectf &r, bool bPartiallyInRectOk)
{
SUHANDLE h;
SURESULT res = Theme_GetShapesInRect(_h, r.x1, r.y1, r.x2, r.y2, bPartiallyInRectOk, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Returns the number of selected objects in this theme.
* \return The number of selected objects.
* \sa Theme_GetSelectionCount()
*/
size_t GetSelectionCount()
{
size_t n;
SURESULT res = Theme_GetSelectionCount(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Queries ShapeUp for the selected shapes in this theme.
* It's important to close the resulting recordset using SURecordset::Close()
* to avoid resource leaks.
* \return A recordset containing shapes.
* \sa SURecordset, Theme_GetSelectedShapes()
*/
SURecordset GetSelectedShapes()
{
SUHANDLE h;
SURESULT res = Theme_GetSelectedShapes(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Queries ShapeUp for the selected shapes in a given rectangle in this theme.
* It's important to close the resulting recordset using SURecordset::Close()
* to avoid resource leaks.
* \param r is a rectangle to compare this theme's shapes to to find
* intersections.
* \param bPartiallyInRectOk if true, this function returns selected shapes
* intersecting the rectangle \a r. If false, only selected shapes fully
* contained in the rectangle \a r is returned.
* \return A recordset containing shapes.
* \sa SURecordset, Theme_GetSelectedShapesInRect()
*/
SURecordset GetSelectedShapesInRect(const SURectf &r, bool bPartiallyInRectOk)
{
SUHANDLE h;
SURESULT res = Theme_GetSelectedShapesInRect(_h, r.x1, r.y1, r.x2, r.y2, bPartiallyInRectOk, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Gets the InfoTip of a shape in the theme. The InfoTip is translated
* from the themes InfoTip Template using attributes of the \a shape.
* \param shape is the shape for which the InfoTip should be retrieved.
* \return The translated InfoTip for the SUShape \a shape.
* \sa SUShape, Theme_GetInfoTip()
*/
std::string GetInfoTip(SUShape shape)
{
size_t bufSize = 0;
SURESULT res = Theme_GetInfoTip(_h, shape, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Theme_GetInfoTip(_h, shape, buf, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
std::string s(buf);
delete [] buf;
return s;
}
/** Gets font information for this theme.
* \param font is a pointer to a LOGFONT struct that will receive the
* font information. May be NULL if not required.
* \param clr is a pointer to a COLORREF value that will receive the
* text color information. May be NULL if not required.
* \sa GetFont()
*/
void GetFont(LOGFONT *font, COLORREF *clr)
{
SURESULT res = Theme_GetFont(_h, font, clr);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Queries ShapeUp for the shapes matching a query string in this theme.
* It's important to close the resulting recordset using SURecordset::Close()
* to avoid resource leaks.
* \param where is an SQL where-statement as found in the ShapeUp Query
* dialog.
* \return A recordset containing shapes.
* \sa SURecordset, Theme_GetShapesByQuery()
*/
SURecordset GetShapesByQuery(const char *where)
{
SUHANDLE h = NULL;
SURESULT res = Theme_GetShapesByQuery(_h, where, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Queries this theme for its parent workspace.
* \return A handle to a ShapeUp workspace.
* \sa Theme_LookupWorkspace()
*/
SUHANDLE LookupWorkspace()
{
SUHANDLE h = NULL;
SURESULT res = Theme_LookupWorkspace(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return h;
}
/** Adds an attribute to this theme.
* \param type is an \ref ATTRIBUTETYPE value indicating the type of
* the attribute.
* \param name is a null-terminated string containing the name of the
* new attribute. This value may not be NULL nor an empty string.
* \param defaultval is a null-terminated string containing an optional
* default value to be added to all shapes. This parameter may be
* NULL.
* \return The index of the created attribute.
* \sa \ref ATTRIBUTETYPE, DeleteAttribute(), Theme_AddAttribute()
*/
size_t AddAttribute(unsigned long type, const char *name, const char *defaultval = NULL)
{
size_t index;
SURESULT res = Theme_AddAttribute(_h, type, name, defaultval, &index);
if (res != SURESULT_OK)
throw SUException(res);
return index;
}
/** Deletes an attribute from this theme.
* \param index is the zero-based index of the attribute.
* \sa AddAttribute(), Theme_DeleteAttribute()
*/
void DeleteAttribute(size_t index)
{
SURESULT res = Theme_DeleteAttribute(_h, index);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets the comment for an attribute.
* \param index is the zero-based index of the attribute.
* \param comment is the new attribute comment.
* Use NULL to clear the comment.
* \sa Theme_SetAttributeComment()
*/
void SetAttributeComment(size_t index, const char *comment)
{
SURESULT res = Theme_SetAttributeComment(_h, index, comment);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the theme comment.
* \return The theme comment.
* \sa Theme_GetComment()
*/
std::string GetComment()
{
size_t bufSize = 0;
SURESULT res = Theme_GetComment(_h, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Theme_GetComment(_h, buf, &bufSize);
if (res != SURESULT_OK)
{
delete [] buf;
throw SUException(res);
}
std::string s(buf);
delete [] buf;
return s;
}
/** Sets the theme comment.
* \param comment is the new theme comment.
* \sa Theme_SetComment()
*/
void SetComment(const char *comment)
{
SURESULT res = Theme_SetComment(_h, comment);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the theme's pen color.
* \return The theme's pen color.
* \sa Theme_GetPenColor()
*/
COLORREF GetPenColor()
{
COLORREF clr;
SURESULT res = Theme_GetPenColor(_h, &clr);
if (res != SURESULT_OK)
throw SUException(res);
return clr;
}
/** Sets the theme's pen color.
* \param clr is the theme's new pen color.
* \sa Theme_SetPenColor()
*/
void SetPenColor(COLORREF clr)
{
SURESULT res = Theme_SetPenColor(_h, clr);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the theme's fill color.
* \return The theme's pen color.
* \sa Theme_GetFillColor()
*/
COLORREF GetFillColor()
{
COLORREF clr;
SURESULT res = Theme_GetFillColor(_h, &clr);
if (res != SURESULT_OK)
throw SUException(res);
return clr;
}
/** Sets the theme's fill color.
* \param clr is the theme's new pen color.
* \sa Theme_SetFillColor()
*/
void SetFillColor(COLORREF clr)
{
SURESULT res = Theme_SetFillColor(_h, clr);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the theme's pen width.
* \return The theme's pen width.
* \sa Theme_GetPenWidth()
*/
size_t GetPenWidth()
{
size_t width;
SURESULT res = Theme_GetPenWidth(_h, &width);
if (res != SURESULT_OK)
throw SUException(res);
return width;
}
/** Sets the theme's pen width.
* \param width is the theme's new pen width.
* \sa Theme_SetPenWidth()
*/
void SetPenWidth(size_t width)
{
SURESULT res = Theme_SetPenWidth(_h, width);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Gets the theme's pen style.
* \return The theme's pen style. For a list of possible
* style values see PENSTYLE.
* \sa Theme_GetPenStyle(), PENSTYLE
*/
size_t GetPenStyle()
{
size_t width;
SURESULT res = Theme_GetPenStyle(_h, &width);
if (res != SURESULT_OK)
throw SUException(res);
return width;
}
/** Sets the theme's pen style.
* \param style is the theme's new pen style. For a list of possible
* style values see PENSTYLE.
* \sa Theme_SetPenStyle(), PENSTYLE
*/
void SetPenStyle(size_t style)
{
SURESULT res = Theme_SetPenStyle(_h, style);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets the theme's pen width.
* \param hbm is a handle to a Windows bitmap. ShapeUp will
* take ownership of the bitmap and destroy it when its no
* longer needed.
* \param west is the western boudary of the raster.
* \param south is the southern boudary of the raster.
* \param east is the eastern boudary of the raster.
* \param north is the northern boudary of the raster.
* \param sourceHint is a description of where the data came from.
* E.g. if loaded from a file, this could be the file name.
* This parameter is informational only, and may be NULL.
* If supplied, it is displayed in the ShapeUp statistical view.
* \sa Theme_SetRasterImage()
*/
void SetRasterImage(HBITMAP hbm, double west, double south, double east, double north, const char *sourceHint)
{
SURESULT res = Theme_SetRasterImage(_h, hbm, west, south, east, north, sourceHint);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Sets data to be serialized with a theme. This function can be
* called at any time setting new data. However, when this function
* is called, any old data is discarded and fully replaced with the
* new.\n
* This data can later be restored from a ShapeUp workspace file
* when it is loaded, if the plug-in has set up a deserialize hook
* using the ShapeUp_AddDeserializeHook call.
* \param byteCount is the size of the \a bytes array.
* \param bytes is a pointer to a byte sequence containing the data to
* be serialized.
* \sa Theme_SetSerialData()
*/
void SetSerialData(size_t byteCount, const void *bytes)
{
SURESULT res = Theme_SetSerialData(_h, byteCount, bytes);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Clears the current shape selection in a theme.
* \sa Theme_ClearSelection()
*/
void ClearSelection()
{
SURESULT res = Theme_ClearSelection(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Clears the current shape selection in a theme.
* \param select is true if selecting and false if deselecting.
* \sa Theme_Select()
*/
void Select(bool select)
{
SURESULT res = Theme_Select(_h, select);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Inverts the current shape selection in this theme.
* \sa Theme_InvertSelection()
*/
void InvertSelection()
{
SURESULT res = Theme_InvertSelection(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
};
/** \brief Wrapper for a ShapeUp workspace.
*
* A ShapeUp workspace manages a number of themes. These themes
* can contain point, line or polygon vector data, or raster
* images. Although the most common scenario is to have one
* workspace opened at a time, ShapeUp supports having multiple
* workspaces opened. Also keep in mind, there might not be a
* workspace at all.
*
* Most hook functions supply a handle to the active workspace,
* or the workspace where the action takes place. These
* workspaces are not necessarily the same!
*
* You may always query ShapeUp for workspaces using the
* ShapeUp_GetWorkspaceCount(), ShapeUp_GetWorkspace() and
* ShapeUp_GetActiveWorkspace() API functions.
*/
class SUWorkspace : public SUObject
{
public:
/** Default constructor.
*/
SUWorkspace() {}
/** Constructor.
* \param hWorkspace is a handle to a ShapeUp workspace.
* \sa ShapeUp_GetWorkspace(), ShapeUp_GetWorkspaceCount(),
* ShapeUp_GetActiveWorkspace()
*/
SUWorkspace(SUHANDLE hWorkspace) : SUObject(hWorkspace) {}
/** Queries the workspace for its map window.
* \return A handle to a ShapeUp map window.
* \sa SUMap, Workspace_GetMapWindow()
*/
SUMap GetMapWindow()
{
SUHANDLE h;
SURESULT res = Workspace_GetMapWindow(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUMap(h);
}
/** Retrieves the number of themes currently in this workspace.
* \return The theme count.
* \sa SUTheme, Workspace_GetThemeCount()
*/
size_t GetThemeCount() const
{
size_t c;
SURESULT res = Workspace_GetThemeCount(_h, &c);
if (res != SURESULT_OK)
throw SUException(res);
return c;
}
/** Retrieves a theme in this workspace.
* \param index is the zero-based index of the theme to retrieve, where 0
* is the topmost layer.
* \return A handle to a ShapeUp theme.
* \sa SUTheme, Workspace_GetTheme()
*/
SUTheme GetTheme(size_t index)
{
SUHANDLE h;
SURESULT res = Workspace_GetTheme(_h, index, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUTheme(h);
}
/** Queries ShapeUp for a single selected theme in this workspace.
* \return A selected theme, or a null-theme if no themes were
* selected or if more than one theme was selected.
* \sa Workspace_GetSelectedTheme()
*/
SUTheme GetSelectedTheme()
{
SUHANDLE h;
SURESULT res = Workspace_GetSelectedTheme(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUTheme(h);
}
/** Queries ShapeUp for the selected themes in this workspace.
* \return A recordset containing themes.
* \sa SURecordset, Workspace_GetSelectedThemes()
*/
SURecordset GetSelectedThemes()
{
SUHANDLE h;
SURESULT res = Workspace_GetSelectedThemes(_h, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SURecordset(h);
}
/** Returns the number of selected themes in this workspace.
* \return The number of selected themes.
* \sa Workspace_GetSelectionCount()
*/
size_t GetSelectionCount()
{
size_t n;
SURESULT res = Workspace_GetSelectionCount(_h, &n);
if (res != SURESULT_OK)
throw SUException(res);
return n;
}
/** Creates a new theme of specified sort in this workspace.
* \param type is the type of objects this theme should contain.
* \param name is a null-terminated string used as the themes initial name.
* This parameter might be NULL to get default naming.
* \return An SUTheme object representing the newly created theme.
* \sa SUTheme, Workspace_CreateNewTheme()
*/
SUTheme CreateNewTheme(ShapeType type, const char* name)
{
SUHANDLE h;
SURESULT res = Workspace_CreateNewTheme(_h, type, name, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUTheme(h);
}
/** Creates a new theme based on the selection in a source theme in this workspace.
* \param source is the theme containing selected shapes to be copied.
* \param name is a null-terminated string used as the themes initial name.
* This parameter might be NULL to get default naming.
* \return An SUTheme object representing the newly created theme.
* \sa SUTheme, Workspace_CreateNewThemeFromSelection()
*/
SUTheme CreateNewThemeFromSelection(SUTheme source, const char* name)
{
SUHANDLE h;
SURESULT res = Workspace_CreateNewThemeFromSelection(_h, source, name, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUTheme(h);
}
/** Opens the Browse Theme dialog, and lets the user select a theme.
* \param title is the title of this dialog. If NULL, the title will
* default to "Select Theme"
* \param theme [out] is an SUTheme that will receive the selected
* theme.
* \return True if a theme was selected, and false if the user
* pressed the cancel button.
* \sa SUTheme, Workspace_BrowseTheme()
*/
bool BrowseTheme(const char* title, SUTheme &theme)
{
SUHANDLE h;
SURESULT res = Workspace_BrowseTheme(_h, title, &h);
if (res != SURESULT_OK)
throw SUException(res);
if (h == NULL)
return false;
theme = SUTheme(h);
return true;
}
/** Gets the workspace's bounding box.
* \param r [out] is a rectangle that will receive the aggregated bounds
* of all themes.
* \sa SUTheme::GetBounds(), Workspace_GetBounds()
*/
void GetBounds(SURectf &r)
{
SURESULT res = Workspace_GetBounds(_h, &r.x1, &r.y1, &r.x2, &r.y2);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Writes a line of text to the console window of this workspace.
* \param line is the text to be written.
* \sa Workspace_Log()
*/
void Log(const char* line)
{
SURESULT res = Workspace_Log(_h, line);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Retrieves the active state of this workspace.
* \return True if this workspace is active, adn false otherrwise.
* \sa Workspace_IsActive()
*/
bool IsActive()
{
BOOL b;
SURESULT res = Workspace_IsActive(_h, &b);
if (res != SURESULT_OK)
throw SUException(res);
return b != 0;
}
/** Forces the workspace to repaint all components.
* \sa Workspace_Refresh()
*/
void Refresh()
{
SURESULT res = Workspace_Refresh(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Loads a JavaScript from file.
* \param file is the name of the JavaScript file to load. If no absolute
* path is given, the script will be searched for relative the
* ShapeUp Scripts sub-directory.
* \return A handle to a loaded SUJavaScript.
* \sa SUJavaScript, ShapeUp_HasJavaScriptSupport(), Workspace_LoadJavaScript()
*/
SUJavaScript LoadJavaScript(const char *file)
{
SUHANDLE h;
SURESULT res = Workspace_LoadJavaScript(_h, file, &h);
if (res != SURESULT_OK)
throw SUException(res);
return SUJavaScript(h);
}
/** Gets the workspace comment found in the workspace properties dialog.
* \return The workspace comment.
* \sa Workspace_GetComment()
*/
std::string GetComment()
{
size_t bufSize = 0;
SURESULT res = Workspace_GetComment(_h, NULL, &bufSize);
if (res != SURESULT_OK)
throw SUException(res);
char *buf = new char[bufSize];
res = Workspace_GetComment(_h, buf, &bufSize);
if (res != SURESULT_OK)
{
delete [] buf;
throw SUException(res);
}
std::string s(buf);
delete [] buf;
return s;
}
/** Sets the workspace comment found in the workspace properties dialog.
* \param comment is the new workspace comment.
* \sa Workspace_SetComment()
*/
void SetComment(const char *comment)
{
SURESULT res = Workspace_SetComment(_h, comment);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Removes a theme from a workspace.
* \param theme is the \ref SUHANDLE to the theme to remove.
* \return true if the theme could be removed, adn false otherwise.
* \sa Workspace_RemoveTheme()
*/
bool RemoveTheme(SUTheme theme)
{
BOOL bOk;
SURESULT res = Workspace_RemoveTheme(_h, theme, &bOk);
if (res != SURESULT_OK)
throw SUException(res);
return (bOk != 0);
}
/** Sets data to be serialized with a workspace. This function can be
* called at any time setting new data. However, when this function
* is called, any old data is discarded and fully replaced with the
* new.\n
* This data can later be restored from a ShapeUp workspace file
* when it is loaded, if the plug-in has set up a deserialize hook
* using the ShapeUp_AddDeserializeHook call.
* \param byteCount is the size of the \a bytes array.
* \param bytes is a pointer to a byte sequence containing the data to
* be serialized.
* \sa Workspace_SetSerialData()
*/
void SetSerialData(size_t byteCount, const void *bytes)
{
SURESULT res = Workspace_SetSerialData(_h, byteCount, bytes);
if (res != SURESULT_OK)
throw SUException(res);
}
/** Adds a new custom data page to the workspace.
* \param name is the name for the new data page.
* \return This function returns the \ref SUHANDLE to the created
* data page on success.
* \sa Workspace_AddDataPage()
*/
SUHANDLE AddDataPage(const char *name)
{
SUHANDLE hDataPage;
SURESULT res = Workspace_AddDataPage(_h, name, NULL, &hDataPage);
if (res != SURESULT_OK)
throw SUException(res);
return hDataPage;
}
/** Deselects all themes in the workspace.
* \return true if the theme could be removed, adn false otherwise.
* \sa Workspace_RemoveTheme()
*/
void ClearSelection()
{
SURESULT res = Workspace_ClearSelection(_h);
if (res != SURESULT_OK)
throw SUException(res);
}
};
#endif
#endif // !SUAPI_NO_IMPLEMENTATION
#endif // _SHAPEUP_API_H