Press on the image to return to the main documentation page.
Dialogs
Written by Andrew Graham
This library contains several modal, that is blocking, dialogs by which the user can enter data. Presently they are an InputDialog for text, a TimeDialog for times, a DateDialog for dates, both a ColorDialog and a ColorPickerDialog for colors, a NumberDialog for numbers,a FileDialog for folders and file names and a CustomDialog.
Android does not provide modal dialogs but a special mechanism to permit this exists in Basic4android. The Android Activity lifetime system makes this support complicated because Activities can be created and destroyed at will by the OS. To avoid stack runaway on the GUI thread when an Activity is destroyed the stack must be unwound to the lowest level. The Basic4android modal mechanism does this by closing any modal dialog being shown and exiting the Sub that called the dialog, and any Sub that called that Sub and so on, in order to return the main thread to the message loop. This means that the application does not necessarily receive a return value from the dialog and has its expected flow of execution interrupted. This will probably most often happen if the device is rotated while a modal dialog is displayed so the Activity is destroyed and rebuilt with a new layout.
Because this may happen unexpectedly applications, depending upon their logical structure, may need code in the Pause and Resume Subs to deal with the fact that modal dialog closure may not always be detected. Setting a process global when a modal dialog is shown and clearing it when it returns with some checking code in the Resume Sub is one way of dealing with this possibility.
The above discussion also applies the Basic4android modal dialogs InputList, InputMultiList, Msgbox and Msgbox2.
This modal dialog allows the user to define a colour by its Red, Green and Blue components. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Returns an integer value representing the color built from the three components and with the specified alpha value. Alpha - A value between 0 to 255 where 0 is fully transparent and 255 is fully opaque.
BlueAsInt
Sets the value of the blue component of the dialog when is intially shown. Returns the value of the blue component of the dialog when it was closed.
GreenAsInt
Sets the value of the green component of the dialog when is intially shown. Returns the value of the green component of the dialog when it was closed.
RedAsInt
Sets the value of the red component of the dialog when is intially shown. Returns the value of the red component of the dialog when it was closed.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
RGBAsInt
Sets the value of the red, green and blue components of the dialog when is intially shown. Returns the color of the red, green and blue components of the dialog when it was closed. Alpha of the provided color is ignored on set and implicitly set to 255 (opaque) on get.
Show (titleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal color dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog allows the user to define a colour by its Hue, Saturation and Value components. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Returns an integer value representing the color built from the three components and with the specified alpha value. Alpha - A value between 0 to 255 where 0 is fully transparent and 255 is fully opaque.
HueAsFloat
Sets the value of the hue component of the dialog when is intially shown. Returns the value of the hue component of the dialog when it was closed. The range of valid numbers for hue is 0.0 to 360.0.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
RGBAsInt
Sets the value of the red, green and blue components of the dialog when is intially shown. Returns the color of the red, green and blue components of the dialog when it was closed. Alpha of the provided color is ignored on set and implicitly set to 255 (opaque) on get.
SaturationAsFloat
Sets the value of the saturation component of the dialog when is intially shown. Returns the value of the saturation component of the dialog when it was closed. The range of valid numbers for saturation is 0.0 to 1.0.
Show (titleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal color dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
Shows a non-modal color dialog. The Dialog_Result event will be raised. Example: DimhsvAsColorDialogHSV DimsfAsObject = hsv.ShowAsync("Choose Color", "Yes", "Cancel", "No", Null, False) WaitFor (sf) Dialog_Result(ResultAsInt) IfResult = DialogResponse.POSITIVEThen Activity.Color = hsv.RGB EndIf
ValueAsFloat
Sets the value of the value component of the dialog when is intially shown. Returns the value of the value component of the dialog when it was closed. The range of valid numbers for value is 0.0 to 1.0.
This modal dialog allows the user to select a colour from a palette of colours. The color may be from a standard palette in the dialog or a custom programmed palette. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Returns an integer value representing the color built from the chosen color and with the specified alpha value. Alpha - A value between 0 to 255 where 0 is fully transparent and 255 is fully opaque.
GetPaletteAt (indexAsInt) AsInt
Gets the value of the color at the specified index in the current palette.
Palette() AsInt
Copies the colours in the array provided to the palette of colors in the dialog. The provided array should contain 15 colors. Returns an integer array that is a copy of the present palette.
ResetPalette
Reset the palette of colors to the standard palette of the dialog.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
RGBAsInt
Sets the value of the chosen color of the dialog when is intially shown. Returns the value of the chosen color of the dialog when it was closed.
SetPaletteAt (indexAsInt, colorAsInt)
Sets the value of the color at the specified index in the current palette. This allows replacing just one or two colors without defining an entire palette.
Show (titleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal color picker dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog displays a custom set of controls laid out on a Basic4android Panel. The Panel is displayed at an abolute position and size within the dialog. It is recommended to use CustomLayoutDialog instead. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Adds the custom layout view, most probably a Panel, to the custom dialog. Although named AddView to match Basic4androd syntax only one view can be added. Adding a view replaces any existing view previously added to the dialog.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
Show (TitleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal custom dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog displays a custom set of controls laid out on a Basic4android Panel. The Panel will be automatically centred in the displayed dialog. It is recommended to use CustomLayoutDialog instead. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Adds the custom layout view, most probably a Panel, to the custom dialog. Although named AddView to match Basic4androd syntax only one view can be added. Adding a view replaces any existing view previously added to the dialog.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
Show (TitleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal custom dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
A customizable dialog. Note that it is supported by Android 4+ (API 14+). This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Events:
Ready (DialogPanel As Panel) Result (Result As Int)
Closes the dialog and raises the Dialog_Result event. Example: DetailsDialog.CloseDialog(DialogResponse.POSITIVE)
GetButton (ButtonTypeAsInt) AsButtonWrapper
Returns one of the dialogs buttons. Returns an uninitialized object if there is no such button. ButtonType - One of the DialogResponse values.
SetSize (WidthAsInt, HeightAsInt)
Sets the dialog size. If not called then the default size will be used. Must be set immediately after the ShowAsync call (before the Ready event). The actualy size of the panel will be smaller, especially the height dimension.
This modal dialog allows the collection of user entered data in the form of a date. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Sets the date value of the dialog when is intially shown. Returns the date value in ticks of the dialog when it is closed.
DayOfMonthAsInt
Sets the day of month value of the dialog when is intially shown. Returns the day of month value of the dialog when it is closed.
MonthAsInt
Sets the month value of the dialog when is intially shown. Returns the month value of the dialog when it is closed.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
SetDate (dayofmonthAsInt, monthAsInt, yearAsInt)
Sets the date values of the dialog when is intially shown.
Show (MessageAsString, TitleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal date input dialog with the specified message and title. Message - The dialog message. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog allows the user to choose a folder and choose or enter a filename. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Sets the filename initially shown to the user. Returns the filename entered or chosen by the user.
FastScrollAsBoolean
Gets or sets whether the fast scroll thumb is displayed by the dialog.
FileFilterAsString
Gets or sets the filter values of the dialog. The filter can be a single value ".txt" The filter can also be a comma separated list of values ".jpg,.png". Note that spaces in filter values are significant and are not ignored. If a filename contains the text of a filter value the file will be displayed. A value of an empty string, the default, will show all files.
FilePathAsString
Sets the file path of the dialog when it is intially shown. Returns the file path of the dialog when it is closed. Note that setting the file path also sets ChosenName to an empty string.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
ScrollingBackgroundColorAsInt
Gets or sets the background color that will be used while scrolling the list. This is an optimization done to make the scrolling smoother. Set to Colors.Transparent if the background behind the list is not solid color. The default whatever is the default for the particular device
Show (TitleAsCharSequence, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal file dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog allows the collection of user entered data in the form of text. The default is free text but the input can be restricted to numeric characters only or to signed numbers including a decimal point. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Gets or sets the text that will appear when the dialog is empty.
HintColorAsInt
Gets or sets the hint text color.
InputAsString
Sets the initial text when the dialog is shown and returns the text entered by the user.
INPUT_TYPE_DECIMAL_NUMBERSAsInt
INPUT_TYPE_NONEAsInt
INPUT_TYPE_NUMBERSAsInt
INPUT_TYPE_PHONEAsInt
INPUT_TYPE_TEXTAsInt
InputTypeAsInt
Sets or returns the input type accepted by the input box.Possible values are: ThisDialogName.INPUT_TYPE_NUMBERS for integer numbers. ThisDialogName.INPUT_TYPE_DECIMAL_NUMBER for signed decimal numbers. ThisDialogName.INPUT_TYPE_TEXT for free text. ThisDialogName.INPUT_TYPE_PHONE for telephone numbers.
PasswordModeAsBoolean
Sets or returns whether this dialog hides the actual characters entered by the user.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
Show (messageAsString, titleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal text input dialog with the specified message and title. Message - The dialog message. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This configurable modal dialog allows the user to enter a number. The dialog is configurable to show any number of digits between a minimum of one and a maximum of eight. The display of a decimal point is optional and the character displayed as the decimal indicator is configurable. Note that the number accepted and returned by the dialog is an integer value and so may need scaling appropriately. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Gets or sets the position of a displayed decimal point in the dialog. Zero displays no decimals, one indicates a single decimal, and so on.
DecimalCharAsChar
Gets or sets the displayed decimal character in the dialog. The default is ".".
DigitsAsInt
Gets or sets the number of digits displayed in the dialog when it is open. One is the minimum, nine is the maximum. The default is five. If ShowSign is True then the leftmost digit will display a "+" or "-".
NumberAsInt
Sets the number initially displayed in the dialog when it is shown. If the number is negative and ShowSign is False then the absolute value is displayed Gets the number entered by the user after the dialog is closed. If ShowSign is True the sign of the number corresponds to the sign entered by the user.
ResponseAsInt [read only]
Returns the response code that the dialog returned when it last closed.
Show (titleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal number picker dialog with the specified title. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
This modal dialog allows the collection of user entered data in the form of a time. The time may be entered in 12 or 24 hour format as determined by the programmer. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Sets the time values of the dialog when is intially shown.
Show (MessageAsString, TitleAsString, PositiveAsString, CancelAsString, NegativeAsString, iconAsandroid.graphics.Bitmap) AsInt
Shows a modal time input dialog with the specified message and title. Message - The dialog message. Title - The dialog title. Positive - The text to show for the "positive" button. Pass "" if you don't want to show the button. Cancel - The text to show for the "cancel" button. Pass "" if you don't want to show the button. Negative - The text to show for the "negative" button. Pass "" if you don't want to show the button. Icon - A bitmap that will be drawn near the title. Pass Null if you don't want to show an icon. Returns one of the DialogResponse values.
Shows a non-modal time dialog. The Dialog_Result event will be raised. Note that this dialog does not show properly in landscape orientation. Example: DimtdAsTimeDialog td.TimeTicks = DateTime.Now DimsfAsObject = td.ShowAsync("", "Select time", "Yes", "", "Cancel", Null, False) WaitFor (sf) Dialog_Result(ResultAsInt) IfResult = DialogResponse.POSITIVEThen Log(DateTime.Time(td.TimeTicks)) EndIf
TimeTicksAsLong
Sets the time value of the dialog when is intially shown. Returns the time value in ticks of the dialog when it is closed.