Xojo Developer Conference
25/27th April 2018 in Denver.
MBS Xojo Conference
6/7th September 2018 in Munich, Germany.

Platforms to show: All Mac Windows Linux Cross-Platform

GetWindowsErrorMessageMBS(ErrorCode as Integer) as String
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 10.1 No Yes No Yes, Windows only No
Function: Formats a windows error message for the given error code.
Example:
EditField1.text = GetWindowsErrorMessageMBS(-2147352567)
Notes: Returns empty string for unknown error codes.

Some examples using this method:

Feedback, Comments & Corrections

WindowsExecuteMBS(ApplicationName as string, CommandLine as string, CurrentDirectory as string, byref PID as Integer, Flags as Integer = 0) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 11.0 No Yes No Yes, Windows only No
Function: Creates a new process and its primary thread. The new process runs in the security context of the calling process.
Example:
dim error, pid as Integer

pid = 0

error = WindowsExecuteMBS("", "explorer.exe", "", pid)
if error = 0 then
MsgBox "Launched explorer with process id: "+str(pid)
else
MsgBox "Error: "+str(error)
end if

pid = 0

error = WindowsExecuteMBS("", "notepad.exe ""C:\boot.ini""", "", pid)
if error = 0 then
MsgBox "Launched Notepad with process id: "+str(pid)
else
MsgBox "Error: "+str(error)
end if
Notes:
ApplicationName:
The name of the module to be executed. This module can be a Windows-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

The string can specify the full path and file name of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification. The function will not use the search path. This parameter must include the file name extension; no default extension is assumed.

The ApplicationName parameter can be empty. In that case, the module name must be the first white space–delimited token in the CommandLine string. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin; otherwise, the file name is ambiguous. For example, consider the string "c:\program files\sub dir\program name". This string can be interpreted in a number of ways. The system tries to interpret the possibilities in the following order:

  • c:\program.exe files\sub dir\program name
  • c:\program files\sub.exe dir\program name
  • c:\program files\sub dir\program.exe name
  • c:\program files\sub dir\program name.exe

If the executable module is a 16-bit application, ApplicationName should be empty, and the string pointed to by CommandLine should specify the executable module as well as its arguments.

To run a batch file, you must start the command interpreter; set ApplicationName to cmd.exe and set CommandLine to the following arguments: /c plus the name of the batch file.

CommandLine:
The command line to be executed. The maximum length of this string is 32,767 characters.. If ApplicationName is empty, the module name portion of CommandLine is limited to MAX_PATH (256) characters.

The CommandLine parameter can be empty. In that case, the function uses the string pointed to by ApplicationName as the command line.

If both ApplicationName and CommandLine are non-empty, the ApplicationName string specifies the module to execute, and the CommandLine string specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. Console processes written in C can use the argc and argv arguments to parse the command line. Because argv[0] is the module name, C programmers generally repeat the module name as the first token in the command line.

If ApplicationName is empty, the first white space–delimited token of the command line specifies the module name. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin (see the explanation for the ApplicationName parameter). If the file name does not contain an extension, .exe is appended. Therefore, if the file name extension is .com, this parameter must include the .com extension. If the file name ends in a period (.) with no extension, or if the file name contains a path, .exe is not appended. If the file name does not contain a directory path, the system searches for the executable file in the following sequence:

  • The directory from which the application loaded.
  • The current directory for the parent process.
  • The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory.
  • The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is System.
  • The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
  • The directories that are listed in the PATH environment variable. Note that this function does not search the per-application path specified by the App Paths registry key. To include this per-application path in the search sequence, use the ShellExecute function.
  • The system adds a terminating null character to the command-line string to separate the file name from the arguments. This divides the original string into two strings for internal processing.

CurrentDirectory:
The full path to the current directory for the process. The string can also specify a UNC path.

If this parameter is empty, the new process will have the same current drive and directory as the calling process. (This feature is provided primarily for shells that need to start an application and specify its initial drive and working directory.)

pid:
The variable to store the process ID of the new process.

Returns 0 for success or a windows error code for any error.

Note that the function returns before the process has finished initialization. If a required DLL cannot be located or fails to initialize, the process is terminated. To get the termination status of a process, call GetExitCodeProcess.

Possible Flags:

ConstantValueDescription
CREATE_BREAKAWAY_FROM_JOB&h01000000The child processes of a process associated with a job are not associated with the job. If the calling process is not associated with a job, this constant has no effect. If the calling process is associated with a job, the job must set the JOB_OBJECT_LIMIT_BREAKAWAY_OK limit.
CREATE_DEFAULT_ERROR_MODE&h04000000The new process does not inherit the error mode of the calling process. Instead, the new process gets the default error mode. This feature is particularly useful for multi-threaded shell applications that run with hard errors disabled. The default behavior is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE&h00000010The new process has a new console, instead of inheriting its parent's console (the default). For more information, see Creation of a Console. This flag cannot be used with DETACHED_PROCESS.
CREATE_NEW_PROCESS_GROUP&h00000200The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+BREAK signal to a group of console processes. If this flag is specified, CTRL+C signals will be disabled for all processes within the new process group. This flag is ignored if specified with CREATE_NEW_CONSOLE.
CREATE_NO_WINDOW&h08000000The process is a console application that is being run without a console window. Therefore, the console handle for the application is not set. This flag is ignored if the application is not a console application, or if it is used with either CREATE_NEW_CONSOLE or DETACHED_PROCESS.
CREATE_PROTECTED_PROCESS&h00040000The process is to be run as a protected process. The system restricts access to protected processes and the threads of protected processes. For more information on how processes can interact with protected processes, see Process Security and Access Rights. To activate a protected process, the binary must have a special signature. This signature is provided by Microsoft but not currently available for non-Microsoft binaries. There are currently four protected processes: media foundation, audio engine, Windows error reporting, and system. Components that load into these binaries must also be signed. Multimedia companies can leverage the first two protected processes. For more information, see Overview of the Protected Media Path. Windows Server 2003 and Windows XP/2000: This value is not supported.
CREATE_PRESERVE_CODE_AUTHZ_LEVEL&h02000000Allows the caller to execute a child process that bypasses the process restrictions that would normally be applied automatically to the process. Windows 2000: This value is not supported.
CREATE_SEPARATE_WOW_VDM&h00000800This flag is valid only when starting a 16-bit Windows-based application. If set, the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run as threads in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that are run in separate VDMs have separate input queues. That means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. The disadvantage of running separately is that it takes significantly more memory to do so. You should use this flag only if the user requests that 16-bit applications should run in their own VDM.
CREATE_SHARED_WOW_VDM&h00001000The flag is valid only when starting a 16-bit Windows-based application. If the DefaultSeparateVDM switch in the Windows section of WIN.INI is TRUE, this flag overrides the switch. The new process is run in the shared Virtual DOS Machine.
CREATE_SUSPENDED&h00000004The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT&h00000400If this flag is set, the environment block pointed to by lpEnvironment uses Unicode characters. Otherwise, the environment block uses ANSI characters.
DEBUG_ONLY_THIS_PROCESS&h00000002The calling thread starts and debugs the new process. It can receive all related debug events using the WaitForDebugEvent function.
DEBUG_PROCESS&h00000001The calling thread starts and debugs the new process and all child processes created by the new process. It can receive all related debug events using the WaitForDebugEvent function. A process that uses DEBUG_PROCESS becomes the root of a debugging chain. This continues until another process in the chain is created with DEBUG_PROCESS. If this flag is combined with DEBUG_ONLY_THIS_PROCESS, the caller debugs only the new process, not any child processes.
DETACHED_PROCESS&h00000008For console processes, the new process does not inherit its parent's console (the default). The new process can call the AllocConsole function at a later time to create a console. For more information, see Creation of a Console. This value cannot be used with CREATE_NEW_CONSOLE.
EXTENDED_STARTUPINFO_PRESENT&h00080000The process is created with extended startup information; the lpStartupInfo parameter specifies a STARTUPINFOEX structure. Windows Server 2003 and Windows XP/2000: This value is not supported.
INHERIT_PARENT_AFFINITY&h00010000The process inherits its parent's affinity. If the parent process has threads in more than one processor group, the new process inherits the group-relative affinity of an arbitrary group in use by the parent. Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000: This value is not supported.
ABOVE_NORMAL_PRIORITY_CLASS&h00008000Process that has priority above NORMAL_PRIORITY_CLASS but below HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS&h00004000Process that has priority above IDLE_PRIORITY_CLASS but below NORMAL_PRIORITY_CLASS.
HIGH_PRIORITY_CLASS&h00000080Process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS&h00000040Process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS&h00000020Process with no special scheduling needs.
REALTIME_PRIORITY_CLASS&h00000100Process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.

Feedback, Comments & Corrections

WindowsRunAsMBS(Username as string, Domain as string, Password as string, LoginFlags as Integer, ApplicationName as string, CommandLine as string, CurrentDirectory as string, byref PID as Integer, Flags as Integer = -1) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 13.2 No Yes No Yes, Windows only No
Function: Runs an application with a different user login.
Notes:
Please see Microsoft website for details:
http://msdn.microsoft.com/en-us/library/windows/desktop/ms682431(v=vs.85).aspx

The plugin passes parameters. If Flags is -1, we use CREATE_DEFAULT_ERROR_MODE Or CREATE_NEW_CONSOLE Or CREATE_NEW_PROCESS_GROUP.
The StartupInfo handles are closed and the PID is returned in the PID parameter.
Returns the Windows error code on failure. Else we return zero for success. On Mac and Linux the result is always -1.

Feedback, Comments & Corrections

WinGetSysColorMBS(Index as Integer) as Color
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 16.2 No Yes No Yes, Windows only No
Function: Retrieves the current color of the specified display element.
Notes:
Display elements are the parts of a window and the display that appear on the system display screen.

Index: The display element whose color is to be retrieved. This parameter can be one of the following values.

NameValueMeaning
COLOR_3DDKSHADOW21Dark shadow for three-dimensional display elements.
COLOR_3DFACE15Face color for three-dimensional display elements and for dialog box backgrounds.
COLOR_3DHIGHLIGHT20Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DHILIGHT20Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DLIGHT22Light color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DSHADOW16Shadow color for three-dimensional display elements (for edges facing away from the light source).
COLOR_ACTIVEBORDER10Active window border.
COLOR_ACTIVECAPTION2Active window title bar.
Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.
COLOR_APPWORKSPACE12Background color of multiple document interface (MDI) applications.
COLOR_BACKGROUND1Desktop.
COLOR_BTNFACE15Face color for three-dimensional display elements and for dialog box backgrounds.
COLOR_BTNHIGHLIGHT20Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_BTNHILIGHT20Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_BTNSHADOW16Shadow color for three-dimensional display elements (for edges facing away from the light source).
COLOR_BTNTEXT18Text on push buttons.
COLOR_CAPTIONTEXT9Text in caption, size box, and scroll bar arrow box.
COLOR_DESKTOP1Desktop.
COLOR_GRADIENTACTIVECAPTION27Right side color in the color gradient of an active window's title bar. COLOR_ACTIVECAPTION specifies the left side color. Use SPI_GETGRADIENTCAPTIONS with the SystemParametersInfo function to determine whether the gradient effect is enabled.
COLOR_GRADIENTINACTIVECAPTION28Right side color in the color gradient of an inactive window's title bar. COLOR_INACTIVECAPTION specifies the left side color.
COLOR_GRAYTEXT17Grayed (disabled) text. This color is set to 0 if the current display driver does not support a solid gray color.
COLOR_HIGHLIGHT13Item(s) selected in a control.
COLOR_HIGHLIGHTTEXT14Text of item(s) selected in a control.
COLOR_HOTLIGHT26Color for a hyperlink or hot-tracked item.
COLOR_INACTIVEBORDER11Inactive window border.
COLOR_INACTIVECAPTION3Inactive window caption.
Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.
COLOR_INACTIVECAPTIONTEXT19Color of text in an inactive caption.
COLOR_INFOBK24Background color for tooltip controls.
COLOR_INFOTEXT23Text color for tooltip controls.
COLOR_MENU4Menu background.
COLOR_MENUHILIGHT29The color used to highlight menu items when the menu appears as a flat menu (see SystemParametersInfo). The highlighted menu item is outlined with COLOR_HIGHLIGHT.
Windows 2000: This value is not supported.
COLOR_MENUBAR30The background color for the menu bar when menus appear as flat menus (see SystemParametersInfo). However, COLOR_MENU continues to specify the background color of the menu popup.
Windows 2000: This value is not supported.
COLOR_MENUTEXT7Text in menus.
COLOR_SCROLLBAR0Scroll bar gray area.
COLOR_WINDOW5Window background.
COLOR_WINDOWFRAME6Window frame.
COLOR_WINDOWTEXT8Text in windows.

The function returns the red, green, blue (RGB) color value of the given element.

Some examples using this method:

Feedback, Comments & Corrections

WinOpenFolderAndSelectItemsMBS(folder as folderitem, files() as folderItem, ShowOnDesktop as Boolean = false, EditName as Boolean = false) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 14.4 No Yes No Yes, Windows only No
Function: Opens a Windows Explorer window with specified items in a particular folder selected.
Example:
dim file as FolderItem = SpecialFolder.Desktop.Child("test.rtf")
dim folder as FolderItem = file.Parent

dim r as Integer = WinOpenFolderAndSelectItemsMBS(folder, array(file))

if r = 0 then
MsgBox "OK"
else
MsgBox "Error: "+str(r)
end if
Notes:
Please pass a folder to open. Pass the files you want to select in that folder.
Returns Windows error code. Zero for success.

Under Windows XP the flag parameters are ignored. They work in Windows Vista and newer:

Editname: Pass true to select an item and put its name in edit mode. This flag can only be used when a single item is being selected. For multiple item selections, it is ignored.

ShowOnDesktop: Pass true to select the item or items on the desktop rather than in a Windows Explorer window. Note that if the desktop is obscured behind open windows, it will not be made visible.

For Mac, please use NSWorkspaceMBS.selectfile function.

Feedback, Comments & Corrections

WinSetSysColorMBS(Index as Integer, value as Color) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Windows MBS Win Plugin 16.2 No Yes No Yes, Windows only No
Function: Sets the colors for the specified display elements.
Notes:
Display elements are the various parts of a window and the display that appear on the system display screen.
If the function succeeds, the return value is true.
For indexes, please check WinGetSysColorMBS.

Some examples using this method:

Feedback, Comments & Corrections

The items on this page are in the following plugins: MBS Win Plugin.




Links
MBS Xojo PDF Plugins