
                    InterDesk Library Function Reference


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDAutoStart(char *command);


Description:

  IDAutoStart() asks the InterDesk Graphical Shell to register the following
  command to be run the next time QNX Windows is started up.


Parameters:

  command       The command to be executed the next time QNXWin starts up.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDragEnd(long drag_id);


Description:

  IDDragEnd()  terminates  the  transfer  of  data  for  the  drag operation 
  specified by  "drag_id".   If  not  as  many  chunks  of  data  have  been 
  transferred  as  were specified in the call to IDDragStart(), the function 
  returns ID_ERR_NOTENOUGHDATA and the drag operation remains unterminated.


Parameters:

  drag_id       ID of the drag operation to be terminated.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDragStart(int src_win, int target_win, short num_chunks,
                    char *data_type, long *drag_id);


Description:

  IDDragStart()  initiates  a  drag-and-drop  operation from a drag-and-drop 
  source window.  The program should specify both  its  own  window  --  the 
  source  window  --  (in the "src_win" parameter), and the target window -- 
  the window to which the objects  were  dragged  --  (in  the  "target_win" 
  parameter).

  The  "num_chunks"  parameter  specifies  the number of chunks of data that 
  will be transferred.  For more information on  chunks,  their  sizes,  and 
  format, see the file "DragDrop.txt".
  
  The  "data_type" parameter specifies the format of the dragged data.  This 
  may not be longer than 32 characters, including the terminating NULL.  For 
  more information on data types and formats, see the file "DragDrop.txt".

  The  "drag_id" parameter returns the drag operation id.  This value should 
  be stored -- it will be used  in  future  function  calls  for  this  drag 
  operation.


Parameters:

  src_win       ID of the source window (QNXWin window id number).

  target_win    ID of the target window (QNXWin window id number).

  num_chunks    Number of chunks of data to be transferred.

  data_type     A  string  (no  longer  than  32  chars,   including   NULL) 
                specifying the type of data to be transferred.

  drag_id       A  pointer  to  a  location  in  which  to  store  the  drag 
                operation's drag identifier.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDragTransfer(long drag_id, void *data, size_t data_len);


Description:

  IDDragTransfer() transfers a chunk of data for a given drag operation.  No 
  chunk  may  be  larger than 8k.  For a list of data types and formats, see 
  the file "DragDrop.txt".

  The "drag_id" parameter specifies the identifier of  the  drag  operation.  
  The  "data"  parameter  holds  the  chunk  of  data,  while the "data_len" 
  parameters specifies the length of the data.


Parameters:

  drag_id       ID of the drag operation.

  data          Data to be transferred.

  data_len      Length of the data.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDropEnd(long drag_id, short file_changed);


Description:

  IDDragEnd()  terminates  the  transfer  of  data  for  the  drop operation 
  specified by  "drag_id".   If  not  as  many  chunks  of  data  have  been 
  received as existed, the extra chunks are discarded and the operation is 
  terminated anyway.

  If the operation was a file transfer (the data type was  "/FileList")  AND 
  any  of  the  files  were changed in any way, the "file_changed" parameter 
  should be set to TRUE, notifying the source window (if it is  a  directory 
  window) that it should re-read its file list.


Parameters:

  drag_id       ID of the drop operation to be terminated.

  file_changed  Whether or not any files received in the drag-and-drop  were 
                changed.   If it was not a file transfer, this should be set 
                to FALSE, also.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDropStart(int src_win, int target_win, short *num_chunks,
                    char *data_type, long *drag_id);


Description:

  IDDropStart() initiates a drag-and-drop  operation  from  a  drag-and-drop 
  target  window.   The program should specify both the source window -- the 
  window from which the object were dragged (in  the  "src_win"  parameter), 
  and  its  own  window  --  the  target  window  --  (in  the  "target_win" 
  parameter).

  The  "num_chunks" parameter returns the number of chunks of data that will 
  be transferred.  For more information on chunks, their sizes, and  format, 
  see the file "DragDrop.txt".
  
  The "data_type" parameter returns the format of the  dragged  data.   This 
  should  have  enough  space  to  hold  32  characters  (that  includes the 
  terminating NULL).  For more information on data types  and  formats,  see 
  the file "DragDrop.txt".

  The  "drag_id" parameter returns the drop operation id.  This value should 
  be stored -- it will be used  in  future  function  calls  for  this  drop 
  operation.


Parameters:

  src_win       ID of the source window (QNXWin window id number).

  target_win    ID of the target window (QNXWin window id number).

  num_chunks    Number of chunks of data to be transferred.

  data_type     A string (at least 32 chars) which returns the type of  data 
                to be transferred.

  drag_id       A  pointer  to  a  location  in  which  to  store  the  drop 
                operation's drag identifier.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDDropTransfer(long drag_id, void *data, size_t *data_len);


Description:

  IDDropTransfer() transfers a chunk of data for a given drop operation.  No 
  chunk may be larger than 8k.  For a list of data types  and  formats,  see 
  the file "DragDrop.txt".

  The  "drag_id"  parameter  specifies the identifier of the drop operation.  
  The "data" parameter receives the chunk  of  data,  while  the  "data_len" 
  parameters returns the length of the data that was received.


Parameters:

  drag_id       ID of the drag operation.

  data          Buffer  in  which to store data.  This must have at least 8k 
                of space to store the data.

  data_len      Returns the length of the received data.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  char *IDErrMsg(short err_val);


Description:

  IDErrMsg() returns the error message corresponding to the InterDesk  error 
  value  given in "err_val".  If the error value is unrecognized, it returns 
  the string "Unrecognized error value".  None of the strings is  terminated 
  with punctuation symbols.


Parameters:

  err_val       Error value to obtain the message of.


Returns:

  A pointer to an internal static string containing an error message.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDRegDragSrc(int win_id, char is_dir_win);


Description:

  IDRegDragSrc()  registers  the  window  specified  by  "win_id"  with  the 
  InterDesk  Graphical  Shell as a drag-and-drop source (i.e., a window from 
  which  objects  may  be  dragged  to  other  windows).   The  "is_dir_win" 
  parameter specifies whether the window is to  be  considered  a  directory 
  window.  If the window is a directory window, it will receive notification 
  when  any  files  dragged  from  it  have changed with a QW_REDRAW message 
  (QW_REDRAW is defined in InterDesk.h).


Parameters:

  win_id        Id of the window to be registered (QNXWin window id number).

  is_dir_win    Boolean  flag  specifying  whether  the  window  is  to   be 
                considered a directory window.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDRegDragTarget(int win_id);


Description:

  IDRegDragTarget()  registers  the  window  specified  by "win_id" with the 
  InterDesk Graphical Shell as a drag-and-drop target (i.e., a  window  into 
  which objects may be dropped).


Parameters:

  win_id        Id of the window to be registered (QNXWin window id number).


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDSourceQuery(int win_id, short *is_source);


Description:

  IDSourceQuery()  asks  the  InterDesk  Graphical  Shell whether the window 
  specified by "win_id" is registered as  a  drag-and-drop  source.   For  a 
  drag-and-drop  target  window,  this  is the first step in a drag-and-drop 
  operation.  If the other involved window is registered as  a  source,  the 
  target  may  proceed  with  the operation.  However, if the other involved 
  window is not  registered  as  a  source,  no  drag  operation  should  be 
  initiated.
  
  Upon  return,  the  value  pointed  to  by  "is_source" is set to indicate 
  whether the specified window is a drag-and-drop source.  It is set to TRUE 
  if the window is a source, or FALSE if it is not a source or if  an  error 
  occurred.


Parameters:

  win_id        ID of the window to be queried (QNXWin window id number).

  is_source     Pointer to a variable in which to store the  result  of  the
                query.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDTargetQuery(int win_id, short *is_target);


Description:

  IDTargetQuery()  asks  the  InterDesk  Graphical  Shell whether the window 
  specified by "win_id" is registered as  a  drag-and-drop  target.   For  a 
  drag-and-drop  source  window,  this  is the first step in a drag-and-drop 
  operation.  If the other involved window is registered as  a  target,  the 
  source  may  proceed  with  the operation.  However, if the other involved 
  window is not  registered  as  a  target,  no  drag  operation  should  be 
  initiated.
  
  Upon  return,  the  value  pointed  to  by  "is_target" is set to indicate 
  whether the specified window is a drag-and-drop target.  It is set to TRUE 
  if the window is a target, or FALSE if it is not a target or if  an  error 
  occurred.


Parameters:

  win_id        ID of the window to be queried (QNXWin window id number).

  is_target     Pointer to a variable in which to store the  result  of  the
                query.


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDUnRegDragSrc(int win_id);


Description:

  IDUnRegDragSrc()  unregisters  the  window  specified by "win_id" with the 
  InterDesk  Graphical  Shell  as  a  drag-and-drop   source.    Unless   it 
  re-registers, it may no longer have objects dragged from it.


Parameters:

  win_id        Id of the window to be unregistered (QNXWin win id number).


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.


----------------------------------------------------------------------------


Synopsis:
  #include "InterDesk.h"
  short IDUnRegDragTarget(int win_id);


Description:

  IDUnRegDragSrc()  unregisters  the  window  specified by "win_id" with the 
  InterDesk  Graphical  Shell  as  a  drag-and-drop   target.    Unless   it 
  re-registers, it may no longer have objects dropped into it.


Parameters:

  win_id        Id of the window to be unregistered (QNXWin win id number).


Returns:

  This function returns ID_SUCCESS(0) if successful, or an InterDesk error 
  value (ID_ERR_xxx) on error.
