wxruby3 1.6.1 → 1.7.0

data/lib/wx/doc/gen/app_traits.rb

@@ -0,0 +1,396 @@
+# :stopdoc:
+# This file is automatically generated by the WXRuby3 documentation 
+# generator. Do not alter this file.
+# :startdoc:
+
+
+module Wx
+
+  # The {Wx::AppTraits} class defines various configurable aspects of a {Wx::App}.
+  # 
+  # You can access it using {Wx::App#get_traits} function and you can create your own {Wx::AppTraits} overriding the {Wx::App#create_traits} function.
+  # Note that {Wx::AppTraits} is an abstract class since it contains many pure virtual functions. In fact, by default, wxWidgets creates a {Wx::ConsoleAppTraits} object for console applications (i.e. those applications linked against {Wx::Base} library only - see the Library List page) and a {Wx::GUIAppTraits} object for GUI applications. Both these classes are derived by {Wx::AppTraits} and represent concrete implementation of the {Wx::AppTraits} interface.
+  # 
+  # Category:  Application and System configuration
+  # @see wxApp Overview
+  # @see  Wx::App 
+  # 
+  # 
+  # 
+  # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
+  class AppTraits < ::Object
+  
+    # Returns the name of the desktop environment currently running on a Unix desktop.
+    # 
+    # It returns an empty string for platforms other than WXGTK, or if the desktop environment could not be determined.
+    # @return [String]
+    def get_desktop_environment; end
+    alias_method :desktop_environment, :get_desktop_environment
+    
+    # Returns the {Wx::StandardPaths} object for the application.
+    # 
+    # It's normally the same for {Wx::Base} and {Wx::GUI} except in the case of WXOSX and {Wx::Cocoa}.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>The returned reference is to a {Wx::StandardPathsBase} class but you can consider it to be equivalent to {Wx::StandardPaths} (which is documented). 
+    # </p>
+    # </div>
+    # @return [Wx::StandardPaths]
+    def get_standard_paths; end
+    alias_method :standard_paths, :get_standard_paths
+    
+    # Returns the wxWidgets port ID used by the running program and eventually fills the given pointers with the values of the major, minor, and micro digits of the native toolkit currently used.
+    # 
+    # The version numbers returned are thus detected at run-time and not compile-time if possible.
+    # E.g. if your program is using WXGTK port this function will return {Wx::PortId::PORT_GTK} and put in given pointers the versions of the GTK library in use. See {Wx::PlatformInfo} for more details.
+    # If a micro version is not available it will have a value of 0.
+    # @return [Array(Wx::PortId,Integer,Integer,Integer)]
+    def get_toolkit_version; end
+    alias_method :toolkit_version, :get_toolkit_version
+    
+    # Returns true if the library was built as {Wx::Universal}.
+    # 
+    # Always returns false for {Wx::Base}-only apps.
+    # @return [Boolean]
+    def is_using_universal_widgets; end
+    alias_method :using_universal_widgets?, :is_using_universal_widgets
+    
+    # Shows the assert dialog with the specified message in GUI mode or just prints the string to stderr in console mode.
+    # 
+    # Returns true to suppress subsequent asserts, false to continue as before.
+    # @param msg [String] 
+    # @return [Boolean]
+    def show_assert_dialog(msg) end
+    
+    # Shows a message box with the given text and title if possible.
+    # 
+    # In some ports, e.g. WXMSW, a message box will always be shown, while in the other ones it will be only done if the GUI is available (e.g. X11 display was successfully opened for X11-based ports) and the function simply returns false without doing anything otherwise.
+    # This function is safe in the sense that it can always be called, even before creating {Wx::App}, similarly to {safe_show_message} which is implemented by calling this function and then logging the message to standard error stream if it returned false.
+    # 
+    # true if the message box was shown or false otherwise.
+    # @param text [String]  The text to show to the user.
+    # @param title [String]  The title of the message box shown to the user.
+    # @return [Boolean]
+    def safe_message_box(text, title) end
+    
+    # Helper function mostly useful for derived classes {Wx::AppTraits#show_assert_dialog} implementation.
+    # 
+    # Returns the stack frame as a plain (and possibly empty) {Wx::String}.
+    # This function is only available when {Wx::Setup::USE_STACKWALKER} is 1.
+    # @return [String]
+    # @wxrb_require USE_STACKWALKER
+    def get_assert_stack_trace; end
+    alias_method :assert_stack_trace, :get_assert_stack_trace
+    
+  end # AppTraits
+  
+  # {Wx::StandardPaths} returns the standard locations in the file system and should be used by applications to find their data files in a portable way.
+  # 
+  # Note that you must not create objects of class {Wx::StandardPaths} directly, but use the global standard paths object returned by {Wx::StandardPaths.get} (which can be of a type derived from {Wx::StandardPaths} and not of exactly this type) and call the methods you need on it. The object returned by {Wx::StandardPaths.get} may be customized by overriding {Wx::AppTraits#get_standard_paths} methods.
+  # In the description of the methods below, the example return values are given for the Unix, Windows and macOS systems, however please note that these are just the examples and the actual values may differ. For example, under Windows: the system administrator may change the standard directories locations, e.g. the Windows directory may be named <code>"W:\Win2003"</code> instead of the default <code>"C:\Windows"</code>.
+  # Notice that in the examples below the string appinfo may be either just the application name (as returned by {Wx::App#get_app_name}) or a combination of the vendor name ({Wx::App#get_vendor_name}) and the application name, with a path separator between them. By default, only the application name is used, use {Wx::StandardPaths#use_app_info} to change this.
+  # The other placeholders should be self-explanatory: the string username should be replaced with the value the name of the currently logged in user. and prefix is only used under Unix and is <code>/usr/local</code> by default but may be changed using {Wx::StandardPaths#set_install_prefix}.
+  # The directories returned by the methods of this class may or may not exist. If they don't exist, it's up to the caller to create them, {Wx::StandardPaths} doesn't do it.
+  # Finally note that these functions only work with standardly packaged applications. I.e. under Unix you should follow the standard installation conventions and under Mac you should create your application bundle according to the Apple guidelines. Again, this class doesn't help you to do it.
+  # This class is MT-safe: its methods may be called concurrently from different threads without additional locking.
+  # 
+  # Category:  File Handling
+  # @see Wx::FileConfig 
+  # 
+  # 
+  # 
+  # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
+  class StandardPaths < ::Object
+  
+    # Possible values for category parameter of {Wx::StandardPaths#get_localized_resources_dir}.
+    # 
+    # 
+    # 
+    class ResourceCat < Wx::Enum
+    
+    end # ResourceCat
+    
+    # Possible values for userDir parameter of {Wx::StandardPaths#get_user_dir}.
+    # 
+    # 
+    # 
+    class Dir < Wx::Enum
+    
+    end # Dir
+    
+    # Possible values for {Wx::StandardPaths#set_file_layout} argument.
+    # 
+    # The elements of this enum correspond to the different file layout standards under Unix systems.
+    # 
+    class FileLayout < Wx::Enum
+    
+    end # FileLayout
+    
+    # Possible values for {Wx::StandardPaths#make_config_file_name} naming convention argument.
+    # 
+    # The values in this enum are only used under Unix and only when using the classic Unix convention for file layout, in XDG mode, XDG naming convention is used unconditionally.
+    # 
+    class ConfigFileConv < Wx::Enum
+    
+    end # ConfigFileConv
+    
+    # Append application and/or vendor name to the given directory.
+    # 
+    # By default, appends the subdirectory with the application name, as returned by {Wx::App#get_app_name}, to the given directory.
+    # This behaviour is affected by {Wx::StandardPaths#use_app_info}, e.g. if this function is called with AppInfo_VendorName then the vendor name would be appended instead of the application name.
+    # @param dir [String] 
+    # @return [String]
+    def append_app_info(dir) end
+    
+    # Return the directory for the document files used by this application.
+    # 
+    # If the application-specific directory doesn't exist, this function returns {Wx::StandardPaths#get_documents_dir}.
+    # Example return values:
+    # 
+    # - Unix: <code>~/appinfo</code> 
+    # - Windows: <code>"C:\Users\username\Documents\appinfo"</code> or <code>"C:\Documents and Settings\username\My Documents\appinfo"</code> 
+    # - Mac: <code>~/Documents/appinfo</code>
+    # @return [String]
+    def get_app_documents_dir; end
+    alias_method :app_documents_dir, :get_app_documents_dir
+    
+    # Return the directory containing the system config files.
+    # 
+    # Example return values:
+    # 
+    # - Unix: <code>/etc</code> 
+    # - Windows: <code>"C:\ProgramData\appinfo"</code> or <code>"C:\Documents and Settings\All Users\Application Data\appinfo"</code> 
+    # - Mac: <code>/Library/Preferences</code> 
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>Under Windows this includes appinfo which makes it inconsistent with other ports.
+    # </p>
+    # </div>
+    # @see Wx::FileConfig 
+    # @return [String]
+    def get_config_dir; end
+    alias_method :config_dir, :get_config_dir
+    
+    # Return the location of the applications global, i.e. not user-specific, data files.
+    # 
+    # Example return values:
+    # 
+    # - Unix: <code>prefix/share/appinfo</code> 
+    # - Windows: the directory where the executable file is located
+    # - Mac: <code>appinfo.app/Contents/SharedSupport</code> bundle subdirectory
+    # 
+    # Under Unix (only) it is possible to override the default value returned from this function by setting the value of WX_APPNAME_DATA_DIR environment variable to the directory to use (where APPNAME is the upper-cased value of {Wx::App#get_app_name}). This is useful in order to be able to run applications using this function without installing them as you can simply set this environment variable to the source directory location to allow the application to find its files there.
+    # @see Wx::StandardPaths#get_local_data_dir 
+    # @return [String]
+    def get_data_dir; end
+    alias_method :data_dir, :get_data_dir
+    
+    # Same as calling {Wx::StandardPaths#get_user_dir} with Dir_Documents parameter.
+    # 
+    # 
+    # @see Wx::StandardPaths#get_app_documents_dir
+    # @see  Wx::StandardPaths#get_user_dir 
+    # @return [String]
+    def get_documents_dir; end
+    alias_method :documents_dir, :get_documents_dir
+    
+    # Return the directory and the filename for the current executable.
+    # 
+    # Example return values:
+    # 
+    # - Unix: <code>/usr/local/bin/exename</code> 
+    # - Windows: <code>"C:\Programs\AppFolder\exename.exe"</code> 
+    # - Mac: <code>/Applications/exename</code>.app/Contents/MacOS/exename
+    # @return [String]
+    def get_executable_path; end
+    alias_method :executable_path, :get_executable_path
+    
+    # Return the program installation prefix, e.g. <code>/usr</code>, <code>/opt</code> or <code>/home/zeitlin</code>.
+    # 
+    # If the prefix had been previously set by {Wx::StandardPaths#set_install_prefix}, returns that value, otherwise tries to determine it automatically (Linux only right now) and finally returns the default <code>/usr/local</code> value if it failed.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function is only available under Unix platforms (but not limited to WXGTK mentioned below).
+    # </p>
+    # </div>
+    # 
+    # Availability:  only available for the WXGTK port.
+    # @return [String]
+    # @wxrb_require WXGTK
+    def get_install_prefix; end
+    alias_method :install_prefix, :get_install_prefix
+    
+    # Return the location for application data files which are host-specific and can't, or shouldn't, be shared with the other machines.
+    # 
+    # This is the same as {Wx::StandardPaths#get_data_dir} except under Unix where it returns <code>/etc/appinfo</code>.
+    # @return [String]
+    def get_local_data_dir; end
+    alias_method :local_data_dir, :get_local_data_dir
+    
+    # Return the localized resources directory containing the resource files of the specified category for the given language.
+    # 
+    # In general this is just the same as lang subdirectory of {Wx::StandardPaths#get_resources_dir} (or lang.lproj under macOS) but is something quite different for message catalog category under Unix where it returns the standard <code>prefix/share/locale/lang/LC_MESSAGES</code> directory.
+    # @param lang [String] 
+    # @param category [Wx::StandardPaths::ResourceCat] 
+    # @return [String]
+    def get_localized_resources_dir(lang, category=RESOURCE_CAT_NONE) end
+    alias_method :localized_resources_dir, :get_localized_resources_dir
+    
+    # Return the directory where the loadable modules (plugins) live.
+    # 
+    # Example return values:
+    # 
+    # - Unix: <code>prefix/lib/appinfo</code> 
+    # - Windows: the directory of the executable file
+    # - Mac: <code>appinfo.app/Contents/PlugIns</code> bundle subdirectory
+    # @see Wx::DynamicLibrary 
+    # @return [String]
+    def get_plugins_dir; end
+    alias_method :plugins_dir, :get_plugins_dir
+    
+    # Return the directory where the application resource files are located.
+    # 
+    # The resources are the auxiliary data files needed for the application to run and include, for example, image and sound files it might use.
+    # This function is the same as {Wx::StandardPaths#get_data_dir} for all platforms except macOS. Example return values:
+    # 
+    # - Unix: <code>prefix/share/appinfo</code> 
+    # - Windows: the directory where the executable file is located
+    # - Mac: <code>appinfo.app/Contents/Resources</code> bundle subdirectory
+    # - iOS: appinfo.app bundle subdirectory
+    # @see Wx::StandardPaths#get_localized_resources_dir 
+    # @return [String]
+    def get_resources_dir; end
+    alias_method :resources_dir, :get_resources_dir
+    
+    # Return the directory for storing temporary files, for the current user.
+    # 
+    # Same as Wx::FileName#get_temp_dir. To create unique temporary files, it is best to use Wx::FileName#create_temp_file_name for correct behaviour when multiple processes are attempting to create temporary files.
+    # @return [String]
+    def get_temp_dir; end
+    alias_method :temp_dir, :get_temp_dir
+    
+    # Return the directory for the user config files.
+    # 
+    # This directory is:
+    # 
+    # - Unix: <code>~</code> (the home directory) or XDG_CONFIG_HOME depending on {Wx::StandardPaths#get_file_layout} return value
+    # - Windows: <code>"C:\Users\username\AppData\Roaming"</code> or <code>"C:\Documents and Settings\username\Application Data"</code> 
+    # - Mac: <code>~/Library/Preferences</code> 
+    # 
+    # Only use this method if you have a single configuration file to put in this directory, otherwise calling {Wx::StandardPaths#append_app_info} with the value returned by GetDir() with {Wx::StandardPaths::Dir_Config} is more appropriate.
+    # @return [String]
+    def get_user_config_dir; end
+    alias_method :user_config_dir, :get_user_config_dir
+    
+    # Return the directory for the user-dependent application data files.
+    # 
+    # The returned path is:
+    # 
+    # - Unix: <code>~/</code>.appinfo
+    # - Windows: <code>"C:\Users\username\AppData\Roaming\appinfo"</code> or <code>"C:\Documents and Settings\username\Application Data\appinfo"</code> 
+    # - Mac: <code>"~/Library/Application Support/appinfo"</code> 
+    # 
+    # Please note that under Unix this function return value doesn't depend on the file layout, and so returns a possibly unexpected value when {Wx::StandardPaths::FileLayout_XDG} is used. Consider using {Wx::StandardPaths#get_user_dir} instead if you use XDG layout, as this function does respect it.
+    # @return [String]
+    def get_user_data_dir; end
+    alias_method :user_data_dir, :get_user_data_dir
+    
+    # Return the path of the specified user data directory.
+    # 
+    # If the value could not be determined the users home directory is returned.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>On Unix this (newer) method always respects the XDG base directory specification, even if {Wx::StandardPaths#set_file_layout} with FileLayout_XDG hadn't been called.
+    # </p>
+    # </div>
+    # @param userDir [Wx::StandardPaths::Dir] 
+    # @return [String]
+    def get_user_dir(userDir) end
+    alias_method :user_dir, :get_user_dir
+    
+    # Return the directory for user data files which shouldn't be shared with the other machines.
+    # 
+    # This is the same as {Wx::StandardPaths#get_user_data_dir} for all platforms except Windows where it returns <code>"C:\Users\username\AppData\Local\appinfo"</code> or <code>"C:\Documents and Settings\username\Local Settings\Application Data\appinfo"</code>
+    # @return [String]
+    def get_user_local_data_dir; end
+    alias_method :user_local_data_dir, :get_user_local_data_dir
+    
+    # Return OS specific directory where project shared libraries are.
+    # 
+    # The function does the same thing as {Wx::StandardPaths#get_plugins_dir} under non-Mac platforms but differs from it under Mac, where plugins (shared libraries loaded by the application dynamically while it's running) and shared libraries (that the application is statically linked with) are stored in different directories.
+    # 
+    # - Windows: returns the folder where the application binary is located
+    # - Unix: returns the libraries installation path, i.e. /usr/lib
+    # - Mac: returns <code>Contents/Frameworks</code> bundle subdirectory
+    # @return [String]
+    def get_shared_libraries_dir; end
+    alias_method :shared_libraries_dir, :get_shared_libraries_dir
+    
+    # Lets {Wx::StandardPaths} know about the real program installation prefix on a Unix system.
+    # 
+    # By default, the value returned by {Wx::StandardPaths#get_install_prefix} is used.
+    # Although under Linux systems the program prefix may usually be determined automatically, portable programs should call this function. Usually the prefix is set during program configuration if using GNU autotools and so it is enough to pass its value defined in config.h to this function.
+    # 
+    # <div class="wxrb-note">
+    # <b>Note:</b>
+    # <p>This function is only available under Unix platforms (but not limited to WXGTK mentioned below).
+    # </p>
+    # </div>
+    # 
+    # Availability:  only available for the WXGTK port.
+    # @param prefix [String] 
+    # @return [void]
+    # @wxrb_require WXGTK
+    def set_install_prefix(prefix) end
+    alias_method :install_prefix=, :set_install_prefix
+    
+    # Controls what application information is used when constructing paths that should be unique to this program, such as the application data directory, the plugins directory on Unix, etc.
+    # 
+    # Valid values for info are:
+    # 
+    # - AppInfo_None: use neither application nor vendor name in the paths.
+    # - AppInfo_AppName: use the application name in the paths.
+    # - AppInfo_VendorName: use the vendor name in the paths, usually used combined with AppInfo_AppName, i.e. as <code>AppInfo_AppName | AppInfo_VendorName</code>.
+    # 
+    # By default, only the application name is used.
+    # @see Wx::StandardPaths#append_app_info
+    # @param info [Integer] 
+    # @return [void]
+    def use_app_info(info) end
+    
+    # Sets the current file layout.
+    # 
+    # The default layout is FileLayout_Classic for compatibility, however newer applications are encouraged to set it to FileLayout_XDG on program startup.
+    # @param layout [Wx::StandardPaths::FileLayout] 
+    # @return [void]
+    def set_file_layout(layout) end
+    alias_method :file_layout=, :set_file_layout
+    
+    # Returns the current file layout.
+    # 
+    # 
+    # @see Wx::StandardPaths#set_file_layout
+    # @return [Wx::StandardPaths::FileLayout]
+    def get_file_layout; end
+    alias_method :file_layout, :get_file_layout
+    
+    # Return the file name which would be used by {Wx::FileConfig} if it were constructed with basename.
+    # 
+    # conv is used to construct the name of the file under Unix and only matters when using the class file layout, i.e. if {Wx::StandardPaths#set_file_layout} had not been called with FileLayout_XDG argument. In this case, this argument is used to determine whether to use an extension or a leading dot. When following XDG specification, the function always appends the extension, regardless of conv value. Finally, this argument is not used at all under non-Unix platforms.
+    # @param basename [String] 
+    # @param conv [Wx::StandardPaths::ConfigFileConv] 
+    # @return [String]
+    def make_config_file_name(basename, conv=CONFIG_FILE_CONV_EXT) end
+    
+    # Returns reference to the unique global standard paths object.
+    # @return [Wx::StandardPaths]
+    def self.get; end
+    
+  end # StandardPaths
+  
+
+end