*** empty log message ***

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@26 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

samples/dnd/d_and_d.txt

@@ -0,0 +1,167 @@
+                        Drag-and-Drop Support in wxWindows
+                        ==================================
+
+1. Overview
+   --------
+
+ a) What is it?
+
+    We're calling drag-and-drop (or d&d for short) the OLE mechanism of data
+transfer. Please note that it's not the same thing as the file oriented d&d
+of Windows 3.1 "File Manager" which is designed for and limited to the file
+names only.
+
+    OLE d&d allows application to transfer data of any type to the same or
+another process.
+
+
+ b) How is it done? (user's point of view)
+
+    To start a d&d operation the user presses the mouse button 1 (left) and
+drags the selected object to another window (which must be at least partially
+visible on the screen) or to an icon on the taskbar in which case the 
+corresponding window will be automatically restored. To finish the operation,
+the user releases the button. Default d&d operation is "move", but several key
+act as modifiers: keeping down the <Ctrl> key at the moment of drop does 
+"copy", while <Shift> or <Alt> force the "move" (makes sense if default isn't
+"move"). 
+
+
+ c) How is it done? (programmer's point of view)
+
+    There are several objects participating in a d&d operation. First of all,
+there is the data object itself. Second, there is the drop source which is
+responsible for creating the data object (if it doesn't exist yet) and starting
+the d&d operation. Finally, the drop target recieves the notification when
+the data is dropped onto the associated window (see below) and is responsible
+for pasting the data and returning the result code (copy, move or failure).
+There is one class for each one of these roles in wxWindows d&d implementation,
+plese see their descriptions below for details.
+
+
+
+2. Drop Target
+   -----------
+
+ a) Being a drop target
+
+    ... is as easy as deriving your window class from wxDropTarget and 
+associating it with a wxWindow object (or perhaps some wxWindow-derived class, 
+such as wxFrame). The pure virtual function wxDropTarget::OnDrop() must be 
+implemented in your application and will be called whenever the mouse button 
+is released over the window in question. Other virtual functions that will be 
+called in the process of the d&d operation are OnEnter and OnLeave.
+
+@@ should OnDragOver() be user overridable also?
+
+  You should associate wxDropTarget and wxWindow calling SetDropTarget:
+    wxWindow *pWindow = GetTopWindow();
+    pWindow->SetDropTarget(new MyDropTarget);
+
+The object created passed to SetDropTarget becomes the propriety of wxWindow
+and will be deleted with the window (or when you call SetDropTarget next
+time). You can always break the association by calling SetDropTarget(NULL).
+
+  When some data is dragged over a window, the program must decide if it's
+going to accept this data or not. The virtual function IsAcceptedData() is
+called to do it. The default implementation takes care of OLE interface
+pointer manipulations and only requires you to override GetCountFormats()
+and GetFormat(n) functions to let it know what data formats you support.
+If it's not flexible enough for your application (i.e. the set of supported
+formats changes over time...), you should override IsAcceptedData(). In 99%
+of cases the default implementation is ok and you only have to return count
+of supported formats (CF_xxx constants or one of your custom formats which
+must have been registered) and their values.
+
+ b) OnDrop(long x, long y, const void *pData)
+
+    (x, y) are drop point (client) coordinates, pData is the pointer to data
+    (whatever it is).
+
+    If 'true' is returned from OnDrop, the operation is considered to be
+    successful and the corresponding code (MOVE or COPY depending on the
+    keyboard control keys) is returned. Otherwise, the operation is cancelled.
+
+    Please remember that returning 'true' here may mean 'move' and so the
+    drop source will delete the corresponding data - which would lead to
+    data loss if you didn't paste it properly.
+
+ c) OnEnter()
+
+    called when the mouse enters the window: you might use this function to
+    give some additional visual feedback.
+
+ d) OnLeave()
+
+    called when the mouse leaves the window; might be a good place to clean
+up things allocated in OnEnter.
+
+ e) Simple wxDropTarget specializations
+
+    Two (very simple) wxDropTarget-derived classes are provided for two most
+common situations: d&d of text and file d&d. To use them you only need to
+override one virtual function OnDropText in wxTextDropTarget's case and
+OnDropFiles for wxFileDropTarget.
+
+    The (x, y) are the same as for OnDrop() function. OnDropText's last
+parameter points to a (always ANSI, not Unicode) text string, while
+OnDropFiles() parameter is the array of file names just dropped (and the
+count of them is passed in the 3rd parameter).
+
+3. Data Object
+   -----------
+
+ a) Drag and drop and clipboard
+
+    The effect of a d&d operation is the same as using the clipboard to
+cut/copy and paste data and it would be nice to use the same code to implement
+these two data transfer mechanisms. The wxDataObject allows you to do exactly
+this. It encapsulates the data which can be passed either through the clipboard
+or d&d.
+
+
+ b) Data format
+
+    There are several standard clipboard formats, such as text, bitmap or 
+metafile picture. All of them are defined in wxDataObject::StdFormats 
+enumeration. Of course, it's not always enough and you'll often need your
+own format for data transfer. The simple helper class wxDataFormat may help
+you: when you create an object of this class, it registers a new clipboard
+data format identified by the string passed to it's ctor.
+
+    After your new format is registered, you may use it as any other one.
+
+4. Drop Source
+   -----------
+
+ a) Starting the d&d operation
+ 
+    In order to start the d&d operation you should call the DoDragDrop function
+(typically in reply to a "mouse button press" message). NB: DoDragDrop() is a
+blocking function which enters into it's own message loop and may return after
+an arbitrarily long time interval. During it, the QueryContinueDrag() is called
+whenever the mouse or keyboard state changes. The default behaviour is quite
+reasonable for 99% of cases: the drag operation is cancelled if the <Esc> key
+is preessed and the drop is initiated if the mouse button is released.
+
+ b) After the end of d&d
+
+    The drop source behaviour depends on DoDragDrop() return code. If it 
+returns wxDropSource::None or wxDropSource::Copy there is normally nothing to
+do, but you shouldn't forget to delete your data if it returns the 
+wxDropSource::Move code.
+
+ c) DoDragDrop
+
+ d) QueryContinueDrag
+
+
+5. Remarks
+   -------
+
+
+@@@@ TODO: support tymed != TYMED_HGLOBAL;
+           better support of CF_BMP, CF_METAFILE
+           scrolling support!! (how?)
+           sample demonstrating use of user-defined formats
+           sample which really does something useful

samples/dnd/dnd.cpp

@@ -0,0 +1,264 @@
+///////////////////////////////////////////////////////////////////////////////
+// Name:        dnd.cpp
+// Purpose:     Drag and drop sample
+// Author:      Vadim Zeitlin
+// Modified by: 
+// Created:     13.11.97
+// RCS-ID:      $Id$
+// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
+// Licence:     wxWindows license
+///////////////////////////////////////////////////////////////////////////////
+
+// ============================================================================
+// headers & declarations
+// ============================================================================
+
+// For compilers that support precompilation, includes "wx.h".
+#include "wx/wxprec.h"
+
+#ifdef __BORLANDC__
+#pragma hdrstop
+#endif
+
+#ifndef WX_PRECOMP
+#include "wx/wx.h"
+#endif
+
+#include  "wx/intl.h"
+#include  "wx/log.h"
+
+#include  "wx/dnd.h"
+
+// ----------------------------------------------------------------------------
+// Derive 2 simple classes which just put in the listbox the strings (text or
+// file names) we drop on them
+// ----------------------------------------------------------------------------
+class DnDText : public wxTextDropTarget
+{
+public:
+  DnDText(wxListBox *pOwner) { m_pOwner = pOwner; }
+
+  virtual bool OnDropText(long x, long y, const char *psz);
+
+private:
+  wxListBox *m_pOwner;
+};
+
+class DnDFile : public wxFileDropTarget
+{
+public:
+  DnDFile(wxListBox *pOwner) { m_pOwner = pOwner; }
+
+  virtual bool OnDropFiles(long x, long y,
+                           size_t nFiles, const char * const aszFiles[]);
+
+private:
+  wxListBox *m_pOwner;
+};
+
+// ----------------------------------------------------------------------------
+// Define a new application type
+// ----------------------------------------------------------------------------
+class DnDApp : public wxApp
+{ 
+public:
+  bool OnInit();
+};
+
+IMPLEMENT_APP(DnDApp);
+
+// ----------------------------------------------------------------------------
+// Define a new frame type
+// ----------------------------------------------------------------------------
+class DnDFrame : public wxFrame
+{ 
+public:
+  DnDFrame(wxFrame *frame, char *title, int x, int y, int w, int h);
+ ~DnDFrame();
+
+  void OnPaint(wxPaintEvent& event);
+  void OnQuit (wxCommandEvent& event);
+  void OnAbout(wxCommandEvent& event);
+  void OnHelp (wxCommandEvent& event);
+
+  bool OnClose();
+  
+  DECLARE_EVENT_TABLE()
+
+private:
+  wxListBox  *m_ctrlFile,
+             *m_ctrlText;
+  wxTextCtrl *m_ctrlLog;
+
+  wxLogTarget *m_pLog, *m_pLogPrev;
+};
+
+// ----------------------------------------------------------------------------
+// IDs for the menu commands
+// ----------------------------------------------------------------------------
+enum
+{
+  Menu_Quit = 1,
+  Menu_About = 101,
+  Menu_Help,
+};
+
+BEGIN_EVENT_TABLE(DnDFrame, wxFrame)
+	EVT_MENU(Menu_Quit,  DnDFrame::OnQuit)
+	EVT_MENU(Menu_About, DnDFrame::OnAbout)
+	EVT_MENU(Menu_Help,  DnDFrame::OnHelp)
+
+  //EVT_PAINT(DnDFrame::OnPaint)
+END_EVENT_TABLE()
+
+// `Main program' equivalent, creating windows and returning main app frame
+bool DnDApp::OnInit(void)
+{
+  // create the main frame window
+  DnDFrame *frame = new DnDFrame(NULL, "Drag & Drop wxWindows App", 
+                                 50, 50, 450, 340);
+
+  // activate it
+  frame->Show(TRUE);
+
+  SetTopWindow(frame);
+
+  return TRUE;
+}
+
+DnDFrame::DnDFrame(wxFrame *frame, char *title, int x, int y, int w, int h)
+        : wxFrame(frame, -1, title, wxPoint(x, y), wxSize(w, h))
+{
+  SetIcon(wxIcon("mondrian"));
+
+  // construct menu
+  wxMenu *file_menu = new wxMenu;
+  file_menu->Append(Menu_Help, "&Help");
+  file_menu->Append(Menu_About, "&About");
+  file_menu->AppendSeparator();
+  file_menu->Append(Menu_Quit, "E&xit");
+  wxMenuBar *menu_bar = new wxMenuBar;
+  menu_bar->Append(file_menu, "&File");
+  SetMenuBar(menu_bar);
+  
+  // make a panel with 3 subwindows
+  wxPoint pos(0, 0);
+  wxSize  size(400, 200);
+
+  wxString strFile("Drop files here!"), strText("Drop text on me");
+
+  m_ctrlFile  = new wxListBox(this, -1, pos, size, 1, &strFile, wxLB_HSCROLL);
+  m_ctrlText  = new wxListBox(this, -1, pos, size, 1, &strText, wxLB_HSCROLL);
+  m_ctrlLog   = new wxTextCtrl(this, -1, "", pos, size, 
+                               wxTE_MULTILINE | wxTE_READONLY | 
+                               wxSUNKEN_BORDER| wxHSCROLL);
+
+  // redirect log messages to the text window (don't forget to delete it!)
+//  m_pLog = new wxLogTextCtrl(m_ctrlLog);
+  m_pLog = NULL;
+  m_pLogPrev = wxLogTarget::SetActiveTarget(m_pLog);
+
+  // associate drop targets with 2 text controls
+  m_ctrlFile->SetDropTarget(new DnDFile(m_ctrlFile));
+  m_ctrlText->SetDropTarget(new DnDText(m_ctrlText));
+
+  wxLayoutConstraints *c;
+
+  c = new wxLayoutConstraints;
+  c->left.SameAs		(this, wxLeft);
+  c->top.SameAs			(this, wxTop);
+  c->right.PercentOf(this, wxRight, 50);
+  c->height.PercentOf(this, wxHeight, 50);
+  m_ctrlFile->SetConstraints(c);
+
+  c = new wxLayoutConstraints;
+  c->left.SameAs    (m_ctrlFile, wxRight);
+  c->top.SameAs     (this, wxTop);
+  c->right.SameAs   (this, wxRight);
+  c->height.PercentOf(this, wxHeight, 50);
+  m_ctrlText->SetConstraints(c);
+
+  c = new wxLayoutConstraints;
+  c->left.SameAs    (this, wxLeft);
+  c->right.SameAs   (this, wxRight);
+  c->height.PercentOf(this, wxHeight, 50);
+  c->bottom.SameAs(this, wxBottom);
+
+  m_ctrlLog->SetConstraints(c);
+
+  SetAutoLayout(TRUE);
+}
+
+void DnDFrame::OnQuit(wxCommandEvent& /* event */)
+{
+  Close(TRUE);
+}
+
+void DnDFrame::OnAbout(wxCommandEvent& /* event */)
+{
+  wxMessageDialog dialog(this, 
+                         "Drag-&-Drop Demo\n"
+                         "Please see File|Help for details",
+                         "About wxDnD");
+
+  dialog.ShowModal();
+}
+
+void DnDFrame::OnHelp(wxCommandEvent& /* event */)
+{
+  wxMessageDialog dialog(this, 
+"This small program demonstrates drag & drop support in wxWindows.\n"
+"The program window consists of 3 parts: the bottom pane is for\n"
+"debug messages, so that you can see what's going on inside.\n"
+"The top part is split into 2 listboxes, the left one accepts\n"
+"files and the right one accepts text.\n"
+"\n"
+"To test it: open wordpad (write.exe), select some text in it and\n"
+"drag it to the right listbox (you'll notice the usual visual\n"
+"feedback, i.e. the cursor will change). Also, try dragging some\n"
+"files (you can select several at once) from Windows Explorer (or\n"
+"File Manager) to the left pane. Hold down Ctrl/Shift keys when\n"
+"you drop text (doesn't work with files) and see what changes.\n"
+"\n"
+"Please address any questions/bug reports/suggestions &c to\n"
+"Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>",
+                        "wxDnD Help");
+
+  dialog.ShowModal();
+}
+
+bool DnDFrame::OnClose() 
+{ 
+  return TRUE; 
+}
+
+DnDFrame::~DnDFrame()
+{
+  if ( m_pLog != NULL ) {
+    if ( wxLogTarget::SetActiveTarget(m_pLogPrev) == m_pLog )
+      delete m_pLog;
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Notifications called by the base class
+// ----------------------------------------------------------------------------
+bool DnDText::OnDropText(long, long, const char *psz)
+{
+  m_pOwner->Append(psz);
+
+  return TRUE;
+}
+
+bool DnDFile::OnDropFiles(long, long, size_t nFiles, 
+                          const char * const aszFiles[])
+{
+  wxString str;
+  str.Printf("%d files dropped", nFiles);
+  m_pOwner->Append(str);
+  for ( size_t n = 0; n < nFiles; n++ ) {
+    m_pOwner->Append(aszFiles[n]);
+  }
+
+  return TRUE;
+}

samples/dnd/dnd.def

@@ -0,0 +1,8 @@
+NAME         DND
+DESCRIPTION  'Drag and drop sample'
+EXETYPE      WINDOWS
+STUB         'WINSTUB.EXE'
+CODE         PRELOAD MOVEABLE DISCARDABLE
+DATA         PRELOAD MOVEABLE MULTIPLE
+HEAPSIZE     4048
+STACKSIZE    16000

samples/dnd/dnd.rc

@@ -0,0 +1,3 @@
+mondrian ICON "mondrian.ico"
+#include "wx/msw/wx.rc"
+

samples/dnd/makefile.b32

@@ -0,0 +1,64 @@
+#
+# File:		makefile.bcc
+# Author:	Julian Smart
+# Created:	1993
+# Updated:	
+# Copyright:	(c) 1993, AIAI, University of Edinburgh
+#
+# "%W% %G%"
+#
+# Makefile : Builds dnd example (DOS).
+
+# WXWIN and BCCDIR are set by parent make
+
+WXDIR = $(WXWIN)
+!include $(WXDIR)\src\makeb32.env
+
+WXLIBDIR = $(WXDIR)\lib
+WXINC = $(WXDIR)\include\msw
+WXLIB = $(WXLIBDIR)\wx32.lib
+LIBS=$(WXLIB) cw32 import32 ole2w32
+
+TARGET=dnd
+
+!if "$(FINAL)" == "0"
+LINKFLAGS=/v /Tpe /L$(WXLIBDIR);$(BCCDIR)\lib
+OPT = -Od
+DEBUG_FLAGS= -v
+!else
+LINKFLAGS=/Tpe /L$(WXLIBDIR);$(BCCDIR)\lib
+OPT = -Od
+DEBUG_FLAGS =
+!endif
+CPPFLAGS=$(DEBUG_FLAGS) $(OPT) @$(CFG)
+
+OBJECTS = dnd.obj
+
+$(TARGET).exe:	$(OBJECTS) $(TARGET).def $(TARGET).res
+  tlink32 $(LINKFLAGS) @&&!
+c0w32.obj $(OBJECTS)
+$(TARGET)
+nul
+$(LIBS)
+$(TARGET).def
+!
+        brc32 -K $(TARGET).res
+
+.$(SRCSUFF).obj:
+	bcc32 $(CPPFLAGS) -c {$< }
+
+.c.obj:
+	bcc32 $(CPPFLAGS) -P- -c {$< }
+
+dnd.obj:      dnd.$(SRCSUFF)
+
+$(TARGET).res :      $(TARGET).rc $(WXDIR)\include\wx\msw\wx.rc
+    brc32 -r /i$(BCCDIR)\include /i$(WXDIR)\include $(TARGET)
+
+clean:
+        -erase *.obj
+        -erase *.exe
+        -erase *.res
+        -erase *.map
+        -erase *.rws
+

samples/dnd/makefile.dos

@@ -0,0 +1,65 @@
+#
+# File:		makefile.dos
+# Author:	Julian Smart
+# Created:	1993
+# Updated:	
+# Copyright:	(c) 1993, AIAI, University of Edinburgh
+#
+# "%W% %G%"
+#
+# Makefile : Builds dnd example (DOS).
+# Use FINAL=1 argument to nmake to build final version with no debugging
+# info
+
+WXDIR = $(WXWIN)
+
+!include $(WXDIR)\src\makemsc.env
+
+THISDIR = $(WXDIR)\samples\dnd
+
+!ifndef FINAL
+FINAL=0
+!endif
+
+HEADERS =
+SOURCES = dnd.$(SRCSUFF)
+OBJECTS = dnd.obj
+
+all:    dnd.exe
+
+wx:
+        cd $(WXDIR)\src\msw
+        nmake -f makefile.dos FINAL=$(FINAL)
+        cd $(THISDIR)
+
+wxclean:
+        cd $(WXDIR)\src\msw
+        nmake -f makefile.dos clean
+        cd $(THISDIR)
+
+dnd.exe:      $(WXDIR)\src\msw\dummy.obj $(WXLIB) dnd.obj dnd.def dnd.res
+        link $(LINKFLAGS) @<<
+dnd.obj $(WXDIR)\src\msw\dummy.obj,
+dnd,
+NUL,
+$(LIBS),
+dnd.def
+;
+<<
+        rc -K dnd.res
+
+dnd.obj:      dnd.$(SRCSUFF)
+        cl @<<
+$(CPPFLAGS) /c /Tp $*.$(SRCSUFF)
+<<
+
+dnd.res :      dnd.rc $(WXDIR)\include\wx\msw\wx.rc
+    rc -r /i$(WXDIR)\include dnd
+
+clean:
+        -erase *.obj
+        -erase *.exe
+        -erase *.res
+        -erase *.map
+        -erase *.sbr
+        -erase *.pdb

samples/dnd/makefile.g95

@@ -0,0 +1,37 @@
+#
+# File:		makefile.unx
+# Author:	Julian Smart
+# Created:	1993
+# Updated:	
+# Copyright:	(c) 1993, AIAI, University of Edinburgh
+#
+# "%W% %G%"
+#
+# Makefile for dnd example (UNIX).
+
+WXDIR = ../..
+
+# All common UNIX compiler flags and options are now in
+# this central makefile.
+include $(WXDIR)/src/makeg95.env
+
+OBJECTS = $(OBJDIR)/dnd.$(OBJSUFF) $(OBJDIR)/dnd_resources.$(OBJSUFF)
+
+all:    $(OBJDIR) dnd$(GUISUFFIX)$(EXESUFF)
+
+wx:
+
+$(OBJDIR):
+	mkdir $(OBJDIR)
+
+dnd$(GUISUFFIX)$(EXESUFF):	$(OBJECTS) $(WXLIB)
+	$(CC) $(LDFLAGS) -o dnd$(GUISUFFIX)$(EXESUFF) $(OBJECTS) $(LDLIBS)
+
+$(OBJDIR)/dnd.$(OBJSUFF):	dnd.$(SRCSUFF)
+	$(CC) -c $(CPPFLAGS) -o $@ dnd.$(SRCSUFF)
+
+$(OBJDIR)/dnd_resources.o:  dnd.rc
+	$(RESCOMP) -i dnd.rc -o $(OBJDIR)/dnd_resources.o $(RESFLAGS)
+
+clean:
+	rm -f $(OBJECTS) dnd$(GUISUFFIX).exe core *.rsc *.res

samples/dnd/makefile.nt

@@ -0,0 +1,64 @@
+#
+# File:		makefile.nt
+# Author:	Julian Smart
+# Created:	1993
+# Updated:	
+# Copyright:	(c) 1993, AIAI, University of Edinburgh
+#
+# "%W% %G%"
+#
+# Makefile : Builds dnd example (MS VC++).
+# Use FINAL=1 argument to nmake to build final version with no debugging
+# info
+
+# Set WXDIR for your system
+WXDIR = $(WXWIN)
+
+WXUSINGDLL=0
+
+!include $(WXDIR)\src\ntwxwin.mak
+
+THISDIR = $(WXDIR)\samples\dnd
+PROGRAM=dnd
+
+OBJECTS = $(PROGRAM).obj
+
+$(PROGRAM):    $(PROGRAM).exe
+
+all:    wx $(PROGRAM).exe
+
+wx:
+        cd $(WXDIR)\src\msw
+        nmake -f makefile.nt FINAL=$(FINAL)
+        cd $(THISDIR)
+
+wxclean:
+        cd $(WXDIR)\src\msw
+        nmake -f makefile.nt clean
+        cd $(THISDIR)
+
+$(PROGRAM).exe:      $(DUMMYOBJ) $(WXLIB) $(OBJECTS) $(PROGRAM).res
+	$(link) @<<
+-out:$(PROGRAM).exe
+$(LINKFLAGS)
+$(DUMMYOBJ) $(OBJECTS) $(PROGRAM).res
+$(LIBS)
+<<
+
+
+$(PROGRAM).obj:      $(PROGRAM).$(SRCSUFF) $(DUMMYOBJ)
+        $(cc) @<<
+$(CPPFLAGS) /c /Tp $*.$(SRCSUFF)
+<<
+
+$(PROGRAM).res :      $(PROGRAM).rc $(WXDIR)\include\wx\msw\wx.rc
+    $(rc) -r /i$(WXDIR)\include -fo$@ $(PROGRAM).rc
+
+
+clean:
+        -erase *.obj
+        -erase *.exe
+        -erase *.res
+        -erase *.map
+        -erase *.sbr
+        -erase *.pdb