SAGA API  v9.5
tool_library.h
Go to the documentation of this file.
1 
3 // //
4 // SAGA //
5 // //
6 // System for Automated Geoscientific Analyses //
7 // //
8 // Application Programming Interface //
9 // //
10 // Library: SAGA_API //
11 // //
12 //-------------------------------------------------------//
13 // //
14 // tool_library.h //
15 // //
16 // Copyright (C) 2006 by Olaf Conrad //
17 // //
18 //-------------------------------------------------------//
19 // //
20 // This file is part of 'SAGA - System for Automated //
21 // Geoscientific Analyses'. //
22 // //
23 // This library is free software; you can redistribute //
24 // it and/or modify it under the terms of the GNU Lesser //
25 // General Public License as published by the Free //
26 // Software Foundation, either version 2.1 of the //
27 // License, or (at your option) any later version. //
28 // //
29 // This library is distributed in the hope that it will //
30 // be useful, but WITHOUT ANY WARRANTY; without even the //
31 // implied warranty of MERCHANTABILITY or FITNESS FOR A //
32 // PARTICULAR PURPOSE. See the GNU Lesser General Public //
33 // License for more details. //
34 // //
35 // You should have received a copy of the GNU Lesser //
36 // General Public License along with this program; if //
37 // not, see <http://www.gnu.org/licenses/>. //
38 // //
39 //-------------------------------------------------------//
40 // //
41 // contact: Olaf Conrad //
42 // Institute of Geography //
43 // University of Goettingen //
44 // Goldschmidtstr. 5 //
45 // 37077 Goettingen //
46 // Germany //
47 // //
48 // e-mail: oconrad@saga-gis.org //
49 // //
51 
52 //---------------------------------------------------------
53 #ifndef HEADER_INCLUDED__SAGA_API__tool_library_H
54 #define HEADER_INCLUDED__SAGA_API__tool_library_H
55 
56 
58 // //
59 // //
60 // //
62 
63 //---------------------------------------------------------
74 // //
76 // //
77 // //
79 
80 //---------------------------------------------------------
81 #include "tool.h"
82 
83 
85 // //
86 // //
87 // //
89 
90 //---------------------------------------------------------
91 typedef enum
92 {
93  TOOL_LIBRARY = 0,
94  TOOL_CHAINS
95 }
96 TSG_Tool_Library_Type;
97 
98 
100 // //
101 // //
102 // //
104 
105 //---------------------------------------------------------
106 class SAGA_API_DLL_EXPORT CSG_Tool_Library
107 {
108  friend class CSG_Tool_Library_Manager;
109 
110 public:
111 
112  virtual TSG_Tool_Library_Type Get_Type (void) const { return( TOOL_LIBRARY ); }
113 
114  bool is_Valid (void) const { return( Get_Count() > 0 ); }
115 
116  const CSG_String & Get_File_Name (void) const { return( m_File_Name ); }
117  const CSG_String & Get_Library_Name (void) const { return( m_Library_Name ); }
118 
119  virtual CSG_String Get_Info (int Type) const;
120  CSG_String Get_Name (void) const { return( Get_Info(TLB_INFO_Name ) ); }
121  CSG_String Get_Description (void) const { return( Get_Info(TLB_INFO_Description) ); }
122  CSG_String Get_Author (void) const { return( Get_Info(TLB_INFO_Author ) ); }
123  CSG_String Get_Version (void) const { return( Get_Info(TLB_INFO_Version ) ); }
124  CSG_String Get_Menu (void) const { return( Get_Info(TLB_INFO_Menu_Path ) ); }
125  CSG_String Get_Category (void) const { return( Get_Info(TLB_INFO_Category ) ); }
126 
127  CSG_String Get_Summary (int Format = SG_SUMMARY_FMT_HTML, bool bInteractive = true) const;
128  bool Get_Summary (const CSG_String &Path) const;
129 
130  virtual int Get_Count (void) const { return( m_pInterface ? m_pInterface->Get_Count() : 0 ); }
131 
132  virtual CSG_Tool * Get_Tool (int Index, TSG_Tool_Type Type = TOOL_TYPE_Base) const;
133  virtual CSG_Tool * Get_Tool (const CSG_String &Name, TSG_Tool_Type Type = TOOL_TYPE_Base) const;
134  virtual CSG_Tool * Get_Tool (const char *Name, TSG_Tool_Type Type = TOOL_TYPE_Base) const;
135  virtual CSG_Tool * Get_Tool (const wchar_t *Name, TSG_Tool_Type Type = TOOL_TYPE_Base) const;
136 
137  virtual CSG_Tool * Create_Tool (int Index, bool bWithGUI = false);
138  virtual CSG_Tool * Create_Tool (const CSG_String &Name, bool bWithGUI = false);
139  virtual CSG_Tool * Create_Tool (const char *Name, bool bWithGUI = false);
140  virtual CSG_Tool * Create_Tool (const wchar_t *Name, bool bWithGUI = false);
141 
142  virtual bool Delete_Tool (CSG_Tool *pTool);
143  virtual bool Delete_Tools (void);
144 
145  virtual CSG_String Get_File_Name (int i) const { return( "" ); }
146  virtual CSG_String Get_Menu (int i) const;
147 
148  void Add_Reference (const CSG_String &Authors, const CSG_String &Year, const CSG_String &Title, const CSG_String &Where, const SG_Char *Link = NULL, const SG_Char *Link_Text = NULL);
149  void Add_Reference (const CSG_String &Link, const SG_Char *Link_Text = NULL);
150  void Del_References (void);
151  const CSG_Strings & Get_References (void) const { return( m_References ); }
152 
153 
154 protected:
155 
156  CSG_Tool_Library(void);
157  CSG_Tool_Library(const CSG_String &File);
158  virtual ~CSG_Tool_Library(void);
159 
160 
161  CSG_String m_File_Name, m_Library_Name;
162 
163 
164 private:
165 
166  bool _Destroy (void);
167 
168 
169  CSG_Strings m_References;
170 
171  CSG_Tool_Library_Interface *m_pInterface;
172 
173  class wxDynamicLibrary *m_pLibrary;
174 
175 };
176 
177 
179 // //
180 // //
181 // //
183 
184 //---------------------------------------------------------
185 class SAGA_API_DLL_EXPORT CSG_Tool_Library_Manager
186 {
187 public:
188  CSG_Tool_Library_Manager(void);
189  virtual ~CSG_Tool_Library_Manager(void);
190 
191  bool Destroy (void);
192 
193  int Get_Count (void) const { return( m_nLibraries ); }
194  int Get_Tool_Count (void) const;
195 
196  CSG_Tool_Library * Add_Library (const CSG_String &File);
197  CSG_Tool_Library * Add_Library (const char *File);
198  CSG_Tool_Library * Add_Library (const wchar_t *File);
199 
200  int Add_Directory (const CSG_String &Directory, bool bOnlySubDirectories = false);
201  int Add_Directory (const char *Directory, bool bOnlySubDirectories = false);
202  int Add_Directory (const wchar_t *Directory, bool bOnlySubDirectories = false);
203 
204  bool Del_Library (int i);
205  bool Del_Library (CSG_Tool_Library *pLibrary);
206 
207  CSG_Tool_Library * Get_Library (int i) const { return( i >= 0 && i < Get_Count() ? m_pLibraries[i] : NULL ); }
208  CSG_Tool_Library * Get_Library (const CSG_String &Name, bool bLibrary) const;
209  CSG_Tool_Library * Get_Library (const char *Name, bool bLibrary) const;
210  CSG_Tool_Library * Get_Library (const wchar_t *Name, bool bLibrary) const;
211 
212  bool is_Loaded (CSG_Tool_Library *pLibrary) const;
213 
214  CSG_Tool * Get_Tool (const CSG_String &Library, int Index) const;
215  CSG_Tool * Get_Tool (const char *Library, int Index) const;
216  CSG_Tool * Get_Tool (const wchar_t *Library, int Index) const;
217  CSG_Tool * Get_Tool (const CSG_String &Library, const CSG_String &Name) const;
218  CSG_Tool * Get_Tool (const char *Library, const char *Name) const;
219  CSG_Tool * Get_Tool (const wchar_t *Library, const wchar_t *Name) const;
220 
221  CSG_Tool * Create_Tool (const CSG_String &Library, int Index, bool bWithGUI = false) const;
222  CSG_Tool * Create_Tool (const char *Library, int Index, bool bWithGUI = false) const;
223  CSG_Tool * Create_Tool (const wchar_t *Library, int Index, bool bWithGUI = false) const;
224  CSG_Tool * Create_Tool (const CSG_String &Library, const CSG_String &Name, bool bWithGUI = false) const;
225  CSG_Tool * Create_Tool (const char *Library, const char *Name, bool bWithGUI = false) const;
226  CSG_Tool * Create_Tool (const wchar_t *Library, const wchar_t *Name, bool bWithGUI = false) const;
227  bool Delete_Tool (CSG_Tool *pTool) const;
228 
229  CSG_String Get_Summary (int Format = SG_SUMMARY_FMT_HTML) const;
230  bool Get_Summary (const CSG_String &Path) const;
231 
232  bool Create_Python_ToolBox (const CSG_String &Destination, bool bClean = true, bool bName = true, bool bSingleFile = false) const;
233 
234 
235 private:
236 
237  int m_nLibraries;
238 
239  CSG_Tool_Library **m_pLibraries;
240 
241 
242  CSG_Tool_Library * _Add_Tool_Chain (const CSG_String &File);
243 
244 };
245 
246 //---------------------------------------------------------
247 SAGA_API_DLL_EXPORT CSG_Tool_Library_Manager & SG_Get_Tool_Library_Manager (void);
248 
249 
251 // //
252 // //
253 // //
255 
256 //---------------------------------------------------------
257 #define SG_RUN_TOOL(bRetVal, LIBRARY, TOOL, CONDITION) {\
258  \
259  bRetVal = false;\
260  \
261  CSG_Tool *pTool = SG_Get_Tool_Library_Manager().Create_Tool(SG_T(LIBRARY), TOOL);\
262  \
263  if( pTool == NULL )\
264  {\
265  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s]", _TL("could not find tool"), SG_T(LIBRARY)));\
266  }\
267  else\
268  {\
269  SG_UI_Process_Set_Text(pTool->Get_Name());\
270  \
271  pTool->Settings_Push();\
272  \
273  if( !pTool->On_Before_Execution() || !(CONDITION) )\
274  {\
275  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s].[%s]", _TL("could not initialize tool"), SG_T(LIBRARY), pTool->Get_Name().c_str()));\
276  }\
277  else if( !pTool->Execute(false) )\
278  {\
279  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s].[%s]", _TL("could not execute tool" ), SG_T(LIBRARY), pTool->Get_Name().c_str()));\
280  }\
281  else\
282  {\
283  bRetVal = true;\
284  }\
285  \
286  SG_Get_Tool_Library_Manager().Delete_Tool(pTool);\
287  }\
288 }
289 
290 #define SG_RUN_TOOL_ExitOnError(LIBRARY, TOOL, CONDITION) {\
291  \
292  bool bResult;\
293  \
294  SG_RUN_TOOL(bResult, LIBRARY, TOOL, CONDITION)\
295  \
296  if( !bResult )\
297  {\
298  return( false );\
299  }\
300 }
301 
302 //---------------------------------------------------------
303 #define SG_RUN_TOOL_KEEP_PARMS(bRetVal, LIBRARY, TOOL, PARMS, CONDITION) {\
304  \
305  bRetVal = false;\
306  \
307  CSG_Tool *pTool = SG_Get_Tool_Library_Manager().Create_Tool(SG_T(LIBRARY), TOOL);\
308  \
309  if( pTool == NULL )\
310  {\
311  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s]", _TL("could not find tool"), SG_T(LIBRARY)));\
312  }\
313  else\
314  {\
315  SG_UI_Process_Set_Text(pTool->Get_Name());\
316  \
317  pTool->Settings_Push();\
318  \
319  if( !pTool->On_Before_Execution() || !(CONDITION) )\
320  {\
321  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s].[%s]", _TL("could not initialize tool"), SG_T(LIBRARY), pTool->Get_Name().c_str()));\
322  }\
323  else if( !pTool->Execute(false) )\
324  {\
325  SG_UI_Msg_Add_Error(CSG_String::Format("%s [%s].[%s]", _TL("could not execute tool" ), SG_T(LIBRARY), pTool->Get_Name().c_str()));\
326  }\
327  else\
328  {\
329  bRetVal = true;\
330  \
331  PARMS.Set_Manager(NULL); PARMS.Assign_Parameters(pTool->Get_Parameters());\
332  }\
333  \
334  SG_Get_Tool_Library_Manager().Delete_Tool(pTool);\
335  }\
336 }
337 
338 #define SG_RUN_TOOL_KEEP_PARMS_ExitOnError(LIBRARY, TOOL, PARMS, CONDITION) {\
339  \
340  bool bResult;\
341  \
342  SG_RUN_TOOL_KEEP_PARMS(bResult, LIBRARY, TOOL, PARMS, CONDITION)\
343  \
344  if( !bResult )\
345  {\
346  return( false );\
347  }\
348 }
349 
350 //---------------------------------------------------------
351 #define SG_TOOL_PARAMETER_SET(IDENTIFIER, VALUE) (pTool->Get_Parameters()->Get_Parameter(IDENTIFIER, true) && pTool->Set_Parameter(IDENTIFIER, VALUE))
352 
353 #define SG_TOOL_PARAMLIST_ADD(IDENTIFIER, VALUE) (\
354  pTool->Get_Parameters()->Get_Parameter(IDENTIFIER, true)\
355  && pTool->Get_Parameters()->Get_Parameter(IDENTIFIER)->asList()\
356  && pTool->Get_Parameters()->Get_Parameter(IDENTIFIER)->asList()->Add_Item(VALUE)\
357 )
358 
359 #define SG_TOOL_SET_DATAOBJECT_LIST(IDENTIFIER, VALUE) (\
360  pTool->Get_Parameters()->Get_Parameter(IDENTIFIER, true)\
361  && pTool->Get_Parameters()->Get_Parameter(IDENTIFIER)->asList()\
362  && pTool->Get_Parameters()->Get_Parameter(IDENTIFIER)->asList()->Assign(VALUE)\
363 )
364 
365 
367 // //
368 // //
369 // //
371 
372 //---------------------------------------------------------
373 #endif // #ifndef HEADER_INCLUDED__SAGA_API__tool_library_H
CSG_Tool_Library_Interface
Definition: tool.h:641
TSG_Tool_Library_Type
TSG_Tool_Library_Type
Definition: tool_library.h:92
CSG_Tool_Library::Get_File_Name
virtual CSG_String Get_File_Name(int i) const
Definition: tool_library.h:145
CSG_Tool_Library_Manager::Get_Tool
CSG_Tool * Get_Tool(const CSG_String &Library, int Index) const
Definition: tool_library.cpp:660
TOOL_LIBRARY
@ TOOL_LIBRARY
Definition: tool_library.h:93
CSG_Tool_Library
Definition: tool_library.h:107
TLB_INFO_Version
@ TLB_INFO_Version
Definition: tool.h:624
CSG_Tool_Library::Get_Name
CSG_String Get_Name(void) const
Definition: tool_library.h:120
TLB_INFO_Category
@ TLB_INFO_Category
Definition: tool.h:626
CSG_Tool
Definition: tool.h:151
SG_Get_Tool_Library_Manager
SAGA_API_DLL_EXPORT CSG_Tool_Library_Manager & SG_Get_Tool_Library_Manager(void)
Definition: tool_library.cpp:286
SG_SUMMARY_FMT_HTML
@ SG_SUMMARY_FMT_HTML
Definition: tool.h:94
TSG_Tool_Type
TSG_Tool_Type
Definition: tool.h:101
TLB_INFO_Name
@ TLB_INFO_Name
Definition: tool.h:621
CSG_Tool_Library_Manager::Delete_Tool
bool Delete_Tool(CSG_Tool *pTool) const
Definition: tool_library.cpp:725
tool.h
CSG_Tool_Library::Get_Version
CSG_String Get_Version(void) const
Definition: tool_library.h:123
CSG_Tool_Library_Manager::Get_Summary
CSG_String Get_Summary(int Format=SG_SUMMARY_FMT_HTML) const
Definition: tool_summary.cpp:791
TLB_INFO_Description
@ TLB_INFO_Description
Definition: tool.h:622
CSG_Tool_Library::Get_Author
CSG_String Get_Author(void) const
Definition: tool_library.h:122
CSG_Tool_Library::Get_File_Name
const CSG_String & Get_File_Name(void) const
Definition: tool_library.h:116
CSG_Tool_Library_Manager::Get_Count
int Get_Count(void) const
Definition: tool_library.h:193
CSG_Tool_Library::Get_Count
virtual int Get_Count(void) const
Definition: tool_library.h:130
CSG_Tool_Library_Manager::Create_Tool
CSG_Tool * Create_Tool(const CSG_String &Library, int Index, bool bWithGUI=false) const
Definition: tool_library.cpp:696
CSG_Tool_Library::Get_Description
CSG_String Get_Description(void) const
Definition: tool_library.h:121
CSG_Tool_Library::Get_Library_Name
const CSG_String & Get_Library_Name(void) const
Definition: tool_library.h:117
CSG_Tool_Library::m_Library_Name
CSG_String m_Library_Name
Definition: tool_library.h:161
SAGA_API_DLL_EXPORT
#define SAGA_API_DLL_EXPORT
Definition: api_core.h:94
CSG_Tool_Library::Get_Menu
CSG_String Get_Menu(void) const
Definition: tool_library.h:124
CSG_Strings
Definition: api_core.h:699
TOOL_CHAINS
@ TOOL_CHAINS
Definition: tool_library.h:94
TLB_INFO_Author
@ TLB_INFO_Author
Definition: tool.h:623
CSG_Tool_Library::Get_Type
virtual TSG_Tool_Library_Type Get_Type(void) const
Definition: tool_library.h:112
CSG_Tool_Library::Get_References
const CSG_Strings & Get_References(void) const
Definition: tool_library.h:151
SG_Char
#define SG_Char
Definition: api_core.h:536
CSG_String
Definition: api_core.h:563
CSG_Tool_Library::is_Valid
bool is_Valid(void) const
Definition: tool_library.h:114
TOOL_TYPE_Base
@ TOOL_TYPE_Base
Definition: tool.h:102
CSG_Tool_Library_Manager::Get_Library
CSG_Tool_Library * Get_Library(int i) const
Definition: tool_library.h:207
CSG_Tool_Library::Get_Category
CSG_String Get_Category(void) const
Definition: tool_library.h:125
CSG_Tool_Library_Manager
Definition: tool_library.h:186
TLB_INFO_Menu_Path
@ TLB_INFO_Menu_Path
Definition: tool.h:625