SDKBrowser Class Reference

#include <lib_browser.h>

Detailed Description

The main browser library class.

Private Member Functions

 SDKBrowser ()
 
 ~SDKBrowser ()
 

SDKBrowserCategory

enum  {
  CategoryPresetNodes,
  CategoryCatalogNodes,
  CategoryDriveNodes,
  CategoryRecentNodes,
  CategorySearchNodes,
  ddumdumdimdum
}
 

SDKBrowserFind

enum  {
  FindExactMatch,
  FindBestMatch,
  ForceDirectoryUpdate
}
 

SDKBrowserFileSystemTypes

enum  {
  Computer,
  Drive,
  DriveCD,
  Folder,
  FolderOpen,
  FolderPresets,
  FolderCatalogs,
  FolderSearch,
  Document,
  ThreeDFile,
  ImageFile,
  MovieFile,
  Preset
}
 

SDKBrowserPresetDb

enum  {
  UserPresetDb,
  InvalidPresetDb
}
 

SDKBrowserPresetLibrary

enum  {
  ReadOnlyPresetLibrary,
  SystemPresetLibrary,
  IgnoreROPresetLibrary
}
 

SDKBrowserPreview

enum  {
  PreviewReplace,
  PreviewAppend
}
 

InsertNodeFromDataBase Callback

typedef SDKBrowserContentNodeRef InsertNodeFromDataBase(SDKBrowserContentNodeRef parent, SDKBrowserContentNodeRef existing_node, const SDKBrowserURL &url, const String &name, UInt32 flags, Int32 db_index, void *user_data)
 

Open New Browser

static Bool OpenNewBrowser (const SDKBrowserURL &path, UInt32 flags=0)
 
static Bool OpenNewBrowserWithTitle (const SDKBrowserURL &path, const String &custom_title=String(), UInt32 flags=0)
 

Category Node

static SDKBrowserContentNodeRef GetCategoryNode (Int32 where)
 

Icon

static SDKBrowserIconGetIcon (Int32 id, Int32 pref_wh=0)
 
static SDKBrowserIconGetIcon (const SDKBrowserURL &url, SDKBrowserPluginRef plugin=0, Int32 flags=0, LocalFileTime *preview_time=0)
 
static SDKBrowserIconGetPreviewIcon (SDKBrowserContentNodeRef content, Int32 pref_wh, Int32 flags=SDKBrowserContentNode::IconPreviewBitmap)
 
static SDKBrowserIconCreateIcon (BaseBitmap *bm, Bool dont_free)
 
static void ReleaseIcon (SDKBrowserIcon *icon)
 

Register Browser Plugin

static Bool RegisterBrowserPlugin (SDKBrowserPluginInterfaceInfo *plugin_info, UInt32 flags=0)
 
static Bool UnregisterBrowserPlugin (SDKBrowserPluginInterfaceInfo *plugin_info)
 

Register Preset Library

static Int32 RegisterPresetLibrary (const SDKBrowserURL &domain, const String &name, const Filename &f)
 
static Bool UnregisterPresetLibrary (Int32 db_index, const Filename &f)
 

Database Index

static Int32 GetDbIndex (const SDKBrowserURL &url, UInt32 flags=0)
 

Preset

static Bool ExistsPreset (const SDKBrowserURL &url)
 
static Bool LoadPreset (Int32 db_index, const SDKBrowserURL &url, Int32 &plugin_id, BaseContainer *bc, void **data, Int *length)
 
static Bool SavePreset (Int32 db_index, const SDKBrowserURL &url, Int32 plugin_id, const BaseContainer *bc, void *data, Int length)
 
static Bool DeletePreset (Int32 db_index, const SDKBrowserURL &url, Int32 plugin_id)
 
static Bool CopyPreset (const SDKBrowserURL &src, const SDKBrowserURL &dst)
 
static Bool GetPresetName (Int32 db_index, const SDKBrowserURL &url, Int32 language_id, String &out_name)
 
static Bool SetPresetName (Int32 db_index, const SDKBrowserURL &url, Int32 language_id, const String &name)
 
static Bool ChangePresetURL (Int32 db_index, const SDKBrowserURL &url, const SDKBrowserURL &new_url, Int32 plugin_id)
 
static Bool GetPresetAnnotation (Int32 db_index, const SDKBrowserURL &url, String &annotation)
 
static Bool SetPresetAnnotation (Int32 db_index, const SDKBrowserURL &url, const String &annotation)
 
static Bool SetPresetPreview (Int32 db_index, const SDKBrowserURL &url, Int32 mode, Int32 preview_quality, BaseBitmap *bm, const LocalFileTime *lft)
 
static BaseBitmapGetPresetPreview (Int32 db_index, const SDKBrowserURL &url, Int32 frame_idx)
 
static Bool GetPresetAnimationData (Int32 db_index, const SDKBrowserURL &url, Int32 *first_frame_idx, Int32 *last_frame_idx, Float *fps)
 
static Bool SetPresetAnimationData (Int32 db_index, const SDKBrowserURL &url, Int32 first_frame_idx, Int32 last_frame_idx, Float fps)
 
static Bool SavePresetObject (const SDKBrowserURL &url, BaseList2D *bl)
 
static Bool ReadNodesFromDatabase (Int32 db_index, const SDKBrowserURL &base_url, SDKBrowserContentNodeRef base_node, InsertNodeFromDataBase *callback, void *user_data)
 
static Bool CreatePresetNode (Int32 db_index, const SDKBrowserURL &url, Int32 plugin_id, Int32 mode=0)
 
static Bool SetPresetSortOrder (SDKBrowserContentNodeRef *nodes, Int32 cnt)
 
static Bool MountPresetLibrary (const Filename &fn, UInt32 flags, SDKBrowserURL *domain=nullptr)
 

Miscellaneous

static void UpdateNotification (SDKBrowserContentNodeRef node, Int32 flags=0)
 
static Int32 PreviewDialogMisc (SubDialog *dlg, void *&private_data, Int32 cmd, Int32 value0=0, Int32 value1=0, void *value2=0, void *value3=0)
 
static SDKBrowserContentNodeRef FindNode (const SDKBrowserURL &url, Int32 flags=FindExactMatch, SDKBrowserContentNodeRef start_from=0)
 
static Bool Identify (const SDKBrowserURL &url, UInt32 flags, SDKBrowserPluginRef *plugin_out)
 

Default Object

static BaseList2DGetDefaultObject (Int32 id, UInt32 flags=0)
 
static Bool SetDefaultObject (BaseList2D *bl, UInt32 flags=0)
 

Member Typedef Documentation

◆ InsertNodeFromDataBase

typedef SDKBrowserContentNodeRef InsertNodeFromDataBase(SDKBrowserContentNodeRef parent, SDKBrowserContentNodeRef existing_node, const SDKBrowserURL &url, const String &name, UInt32 flags, Int32 db_index, void *user_data)

Node insertion callback.

Parameters
[in]parentThe parent node.
[in]existing_nodeAn existing node.
[in]urlThe URL.
[in]nameThe name.
[in]flagsThe flags.
[in]db_indexThe database index.
[in]user_dataThe callback user data.
Returns
A content node.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
Enumerator
CategoryPresetNodes 

Preset category.

CategoryCatalogNodes 

Catalog category.

CategoryDriveNodes 

Drive category.

CategoryRecentNodes 

Recent category.

CategorySearchNodes 

Search category.

ddumdumdimdum 

◆ anonymous enum

anonymous enum
Enumerator
FindExactMatch 

Find exact match.

FindBestMatch 

Find best match.

ForceDirectoryUpdate 

Force directory update.

◆ anonymous enum

anonymous enum
Enumerator
Computer 

Computer.

Drive 

Drive.

DriveCD 

CD drive.

Folder 

Folder.

FolderOpen 

Open folder.

FolderPresets 

Presets folder.

FolderCatalogs 

Catalogs folder.

FolderSearch 

Search folder.

Document 

Document folder.

ThreeDFile 

3D file.

ImageFile 

Image file.

MovieFile 

Movie file.

Preset 

Preset.

◆ anonymous enum

anonymous enum
Enumerator
UserPresetDb 

User preset library database index.

InvalidPresetDb 

Invalid database index.

◆ anonymous enum

anonymous enum
Enumerator
ReadOnlyPresetLibrary 

Disable write operations to the preset library (regardless of the file system settings).

SystemPresetLibrary 

System preset library.

IgnoreROPresetLibrary 

Ignore a read-only flag in the preset library and makes it writable.

◆ anonymous enum

anonymous enum
Enumerator
PreviewReplace 

Previews are replaced.

PreviewAppend 

Previews are appended.

Constructor & Destructor Documentation

◆ SDKBrowser()

SDKBrowser ( )
private

◆ ~SDKBrowser()

~SDKBrowser ( )
private

Member Function Documentation

◆ OpenNewBrowser()

static Bool OpenNewBrowser ( const SDKBrowserURL path,
UInt32  flags = 0 
)
static

Opens a new browser at path.

Parameters
[in]pathThe path to open.
[in]flagsThe flags.
Returns
true if successful, otherwise false.

◆ OpenNewBrowserWithTitle()

static Bool OpenNewBrowserWithTitle ( const SDKBrowserURL path,
const String custom_title = String(),
UInt32  flags = 0 
)
static

Opens a new browser at path with a custom title.

Parameters
[in]pathThe path to open.
[in]custom_titleThe custom title.
[in]flagsThe flags.
Returns
true if successful, otherwise false.

◆ GetCategoryNode()

static SDKBrowserContentNodeRef GetCategoryNode ( Int32  where)
static

Gets a category node.

Parameters
[in]whereThe category. See SDKBrowserCategory.
Returns
The category node, or nullptr if it could not be found.

◆ GetIcon() [1/2]

static SDKBrowserIcon* GetIcon ( Int32  id,
Int32  pref_wh = 0 
)
static

Gets an icon by ID.

Parameters
[in]idThe icon ID.
[in]pref_whThe preferred width/height of the icon.
Returns
The icon.

◆ GetIcon() [2/2]

static SDKBrowserIcon* GetIcon ( const SDKBrowserURL url,
SDKBrowserPluginRef  plugin = 0,
Int32  flags = 0,
LocalFileTime preview_time = 0 
)
static

Gets an icon by URL and plugin ID.

Parameters
[in]urlA URL to get the icon for.
[in]pluginA corresponding plugin ID.
[in]flagsReserved.
[in]preview_timeAn optional preview time.
Returns
The icon.

◆ GetPreviewIcon()

static SDKBrowserIcon* GetPreviewIcon ( SDKBrowserContentNodeRef  content,
Int32  pref_wh,
Int32  flags = SDKBrowserContentNode::IconPreviewBitmap 
)
static

Retrieves the pointer to a preview icon. If no preview is available the default icon for the type of node will be returned. The browser will cache the icon.

Parameters
[in]contentThe node for which an icon will be returned.
[in]pref_whThe preferred width/height of the icon.
[in]flagsThe flags. See SDKBrowserIconFlags.
Returns
The icon.

◆ CreateIcon()

static SDKBrowserIcon* CreateIcon ( BaseBitmap bm,
Bool  dont_free 
)
static

Creates an icon from a bitmap.

Parameters
[in]bmThe bitmap to create the icon from.
[in]dont_freetrue if the icon bitmap should not be freed.
Returns
The icon.

◆ ReleaseIcon()

static void ReleaseIcon ( SDKBrowserIcon icon)
static

Releases icon.

Parameters
[in,out]iconThe icon to release.

◆ RegisterBrowserPlugin()

static Bool RegisterBrowserPlugin ( SDKBrowserPluginInterfaceInfo plugin_info,
UInt32  flags = 0 
)
static

Registers the browser plugin in plugin_info.

Parameters
[in]plugin_infoThe browser plugin to register.
[in]flagsThe flags.
Returns
true if successful, otherwise false.

◆ UnregisterBrowserPlugin()

static Bool UnregisterBrowserPlugin ( SDKBrowserPluginInterfaceInfo plugin_info)
static

Unregisters the browser plugin in plugin_info.

Parameters
[in]plugin_infoThe browser plugin to unregister.
Returns
true if successful, otherwise false.

◆ RegisterPresetLibrary()

static Int32 RegisterPresetLibrary ( const SDKBrowserURL domain,
const String name,
const Filename f 
)
static

Registers a preset library.

Parameters
[in]domainThe preset domain.
[in]nameThe name of the database.
[in]fThe file name and path.
Returns
The database index of the registered preset library, or < 0 if an error occurred.

◆ UnregisterPresetLibrary()

static Bool UnregisterPresetLibrary ( Int32  db_index,
const Filename f 
)
static

Unregisters a preset library.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]fThe file name and path.
Returns
true if successful, otherwise false.

◆ GetDbIndex()

static Int32 GetDbIndex ( const SDKBrowserURL url,
UInt32  flags = 0 
)
static

Gets the database index of url.

Parameters
[in]urlThe URL to get the database index for.
[in]flagsThe flags.
Returns
The database index, or InvalidPresetDb if url does not belong to any preset database.

◆ ExistsPreset()

static Bool ExistsPreset ( const SDKBrowserURL url)
static

Checks if a preset exists.

Parameters
[in]urlThe URL of the preset.
Returns
true if a preset exists at url, otherwise false.

◆ LoadPreset()

static Bool LoadPreset ( Int32  db_index,
const SDKBrowserURL url,
Int32 plugin_id,
BaseContainer bc,
void **  data,
Int length 
)
static

Loads data for a preset node in a specific preset database.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[out]plugin_idAssigned The ID of the plugin that saved the data.
[out]bcAssigned an information container. Can be nullptr.
[out]dataAssigned a memory block with private node data. The memory will be owned by the caller. Can be nullptr.
[out]lengthAssigned the length of the private node data in bytes.
Returns
true if successful, otherwise false.

◆ SavePreset()

static Bool SavePreset ( Int32  db_index,
const SDKBrowserURL url,
Int32  plugin_id,
const BaseContainer bc,
void *  data,
Int  length 
)
static

Saves data for a preset node in a specific preset database.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]plugin_idThe ID of the plugin that saves the data. (This should be the same value as SDKBrowserPluginInterface::GetPluginID().)
[in]bcPointer to an information container. Can be nullptr.
[in]dataMemory block with private node data. The caller owns the memory block. Can be nullptr.
[in]lengthThe length of the private node data in bytes.
Returns
true if successful, otherwise false.

◆ DeletePreset()

static Bool DeletePreset ( Int32  db_index,
const SDKBrowserURL url,
Int32  plugin_id 
)
static

Deletes data for a preset node in a specific preset database.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]plugin_idThe ID of the plugin that saves the data. (This should be the same value as SDKBrowserPluginInterface::GetPluginID().)
Returns
true if successful, otherwise false.

◆ CopyPreset()

static Bool CopyPreset ( const SDKBrowserURL src,
const SDKBrowserURL dst 
)
static

Copies presets.

Parameters
[in]srcThe URL of the source preset.
[in]dstThe URL of the destination preset.
Returns
true if successful, otherwise false.

◆ GetPresetName()

static Bool GetPresetName ( Int32  db_index,
const SDKBrowserURL url,
Int32  language_id,
String out_name 
)
static

Retrieves the language specific name of a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]language_idThe language ID. LanguageDefault for the default language. See SDKBrowserLanguage.
[out]out_nameAssigned the preset name.
Returns
true if successful, otherwise false.

◆ SetPresetName()

static Bool SetPresetName ( Int32  db_index,
const SDKBrowserURL url,
Int32  language_id,
const String name 
)
static

Sets the language specific name of a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]language_idThe language ID. LanguageDefault for the default language. See SDKBrowserLanguage.
[in]nameThe new name..
Returns
true if successful, otherwise false.

◆ ChangePresetURL()

static Bool ChangePresetURL ( Int32  db_index,
const SDKBrowserURL url,
const SDKBrowserURL new_url,
Int32  plugin_id 
)
static

Changes the preset URL.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]new_urlThe new URL.
[in]plugin_idThe ID of the plugin that saved the data (this should be the same value as SDKBrowserPluginInterface::GetPluginID()).
Returns
true if successful, otherwise false.

◆ GetPresetAnnotation()

static Bool GetPresetAnnotation ( Int32  db_index,
const SDKBrowserURL url,
String annotation 
)
static

Retrieves the annotation string of a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[out]annotationAssigned the annotation.
Returns
true if successful, otherwise false.

◆ SetPresetAnnotation()

static Bool SetPresetAnnotation ( Int32  db_index,
const SDKBrowserURL url,
const String annotation 
)
static

Sets the annotation string of a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]annotationThe new annotation.
Returns
true if successful, otherwise false.

◆ SetPresetPreview()

static Bool SetPresetPreview ( Int32  db_index,
const SDKBrowserURL url,
Int32  mode,
Int32  preview_quality,
BaseBitmap bm,
const LocalFileTime lft 
)
static

Sets the preview bitmap of a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]modeThe mode. See SDKBrowserPreview.
[in]preview_qualityThe new preview quality. See SDKBrowserPreviewQuality.
[in]bmThe preview bitmap. Copied.
[in]lftThe preview time. Copied.
Returns
true if successful, otherwise false.

◆ GetPresetPreview()

static BaseBitmap* GetPresetPreview ( Int32  db_index,
const SDKBrowserURL url,
Int32  frame_idx 
)
static

Gets the preview bitmap for a preset.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]frame_idxThe frame index, for movie clip previews.
Returns
The preview bitmap.

◆ GetPresetAnimationData()

static Bool GetPresetAnimationData ( Int32  db_index,
const SDKBrowserURL url,
Int32 first_frame_idx,
Int32 last_frame_idx,
Float fps 
)
static

Retrieves the animation data for an animated preset preview.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[out]first_frame_idxAssigned the number of the first frame.
[out]last_frame_idxAssigned the number of the last frame.
[out]fpsAssigned the frames per second.
Returns
true if successful, otherwise false.

◆ SetPresetAnimationData()

static Bool SetPresetAnimationData ( Int32  db_index,
const SDKBrowserURL url,
Int32  first_frame_idx,
Int32  last_frame_idx,
Float  fps 
)
static

Sets the animation data for an animated preset preview.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL of the preset node.
[in]first_frame_idxThe number of the first frame.
[in]last_frame_idxThe number of the last frame.
[in]fpsAssigned the frames per second.
Returns
true if successful, otherwise false.

◆ SavePresetObject()

static Bool SavePresetObject ( const SDKBrowserURL url,
BaseList2D bl 
)
static

Saves a BaseList2D object as preset. An already existing node with the url will be replaced.

Parameters
[in]urlThe URL of the preset node. There must be an existing node for the URL!
[in]blThe base list object.
Returns
true if successful, otherwise false.

◆ ReadNodesFromDatabase()

static Bool ReadNodesFromDatabase ( Int32  db_index,
const SDKBrowserURL base_url,
SDKBrowserContentNodeRef  base_node,
InsertNodeFromDataBase callback,
void *  user_data 
)
static

Reads nodes from a database.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]base_urlThe base URL.
[in]base_nodeThe base node.
[in]callbackThe callback.
[in]user_dataThe user data for the callback.
Returns
true if successful, otherwise false.

◆ CreatePresetNode()

static Bool CreatePresetNode ( Int32  db_index,
const SDKBrowserURL url,
Int32  plugin_id,
Int32  mode = 0 
)
static

Creates a new preset node.

Parameters
[in]db_indexThe database index. Use UserPresetDb for the user preset library, or a value from GetDbIndex() or RegisterPresetLibrary().
[in]urlThe URL to create the preset node for.
[in]plugin_idThe ID of the plugin for the preset node (this should be the same value as SDKBrowserPluginInterface::GetPluginID()).
[in]modeThe preset mode.
Returns
true if successful, otherwise false.

◆ SetPresetSortOrder()

static Bool SetPresetSortOrder ( SDKBrowserContentNodeRef nodes,
Int32  cnt 
)
static

Used to define a custom preset order for a directory.
When iterating through the nodes in a directory the content browser will return them in the order that is specified in the array nodes.
BodyPaint 3D for example uses this function to change the order of the brush presets.

Parameters
[in]nodesThe nodes array.
[in]cntThe length of the nodes array.
Returns
true if successful, otherwise false.

◆ MountPresetLibrary()

static Bool MountPresetLibrary ( const Filename fn,
UInt32  flags,
SDKBrowserURL domain = nullptr 
)
static

Mounts a preset library.

Parameters
[in]fnThe file name of the library to load.
[in]flagsThe flags. See SDKBrowserPresetLibrary.
[out]domainAssigned the domain of the preset, can be nullptr.
Returns
true if successful, otherwise false.

◆ UpdateNotification()

static void UpdateNotification ( SDKBrowserContentNodeRef  node,
Int32  flags = 0 
)
static

Tells the browser about changes in node.

Parameters
[in]nodeThe modified node (or parent node).
[in]flagsReserved.

◆ PreviewDialogMisc()

static Int32 PreviewDialogMisc ( SubDialog dlg,
void *&  private_data,
Int32  cmd,
Int32  value0 = 0,
Int32  value1 = 0,
void *  value2 = 0,
void *  value3 = 0 
)
static

Private.

◆ FindNode()

static SDKBrowserContentNodeRef FindNode ( const SDKBrowserURL url,
Int32  flags = FindExactMatch,
SDKBrowserContentNodeRef  start_from = 0 
)
static

Retrieves the browser content node corresponding to url.

Parameters
[in]urlThe URL of the node.
[in]flagsThe flags. See SDKBrowserFind.
[in]start_fromAn optional start node.
Returns
The found node, or nullptr if no node was found.

◆ Identify()

static Bool Identify ( const SDKBrowserURL url,
UInt32  flags,
SDKBrowserPluginRef plugin_out 
)
static

Identifies url.

Parameters
[in]urlThe URL to identify.
[in]flagsThe flags.
[in]plugin_outAssigned the corresponding plugin, if found.
Returns
true if successful, otherwise false.

◆ GetDefaultObject()

static BaseList2D* GetDefaultObject ( Int32  id,
UInt32  flags = 0 
)
static

Retrieves a default object of type id if available.

Parameters
[in]idThe object type.
[in]flagsThe flags.
Returns
A clone of the default object. The caller owns the pointed object.

◆ SetDefaultObject()

static Bool SetDefaultObject ( BaseList2D bl,
UInt32  flags = 0 
)
static

Sets a default object for the type of bl, overwriting older default library objects for this type.

Parameters
[in]blThe new default object. The object is cloned. The caller owns the pointed object.
[in]flagsThe flags.
Returns
true if successful, otherwise false.