02 Common properties

In this section all properties, which are common for all preferences, which are provided by the library, will be discussed. These properties can be set by either using the setter methods, which are provided by the common base class DialogPreference, or by specifying the preference via a XML resource.

2.1 Getter and setter methods

In case, the preference has been instantiated programatically, the class DialogPreference provides the following getter and setter methods in addition to the methods, which are inherited from its base class Preference.

Getter and setter methods	Description	Default value	Restrictions
getDialogTitle():CharSequence setDialogTitle(CharSequence):void setDialogTitle(int):void	Returns or sets the title of the preference's dialog. If the title is null or empty, the preference's title will be used.	null	If the title is specified via a resource ID, the ID must correspond to a valid string resource.
getDialogMessage():CharSequence setDialogMessage(CharSequence):void setDialogMessage(int):void	Returns or sets the message of the preference's dialog. If the message is null or empty, no message will be shown.	null	If the message is specified via a resource ID, the ID must correspond to a valid string resource.
getDialogIcon():Drawable setDialogIcon(Drawable):void setDialogIcon(int):void	Returns or sets the icon of the preference's dialog. If the icon is null, no icon will be shown.	null	If the icon is specified via a resource ID, the ID must correspond to a valid drawable resource.
getDialogTitleColor():int setDialogTitleColor(int):void	Returns or sets the color of the title of the preference's dialog. If the color is -1, the color ?attr/colorPrimary is used.	-1	none
getDialogMessageColor():int setDialogMessageColor(int):void	Returns or sets the color of the message of the preference's dialog. If the color is -1, the color ?android:attr/textColorSecondary is used.	-1	none
getDialogBackground():Drawable setDialogBackground(Drawable):void setDialogBackground(int):void setDialogBackgroundColor(int):void	Returns or sets the background of the preference's dialog. If the background is null, the color ?android:attr/background is used.	null	If the background is specified via a resource ID, the ID must correspond to a valid drawable resource.
getDialogWindowBackground():Drawable setDialogWindowBackground(int):void setDialogWindowBackground(Bitmap):void	Returns or sets the window background of the preference's dialog. This allows to customize the shape of the dialog by specifying a 9-patch drawable with white and transparent areas.	android.R.drawable.dialog_holo_light_frame	If the window background is specified via a resource ID, the resource ID must correspond to a valid drawable resource.
getDialogButtonTextColor():int setDialogButtonTextColor(int):void	Returns or sets the text color of the buttons of the preference's dialog. If the color is -1, the color ?attr/colorAccent is used.	null	none
getDialogDisabledButtonTextColor():int setDialogDisabledButtonTextColor(int):void	Returns or sets the disabled text color of the buttons of the preference's dialog. If the color is -1, the color #42000000 or #4dffffff is used depending on the used theme	null	none
getNegativeButton():CharSequence setNegativeButton(CharSequence):void setNegativeButton(int):void	Returns or sets the text of the negative button of the preference's dialog. If the text is null or empty, no such button will be shown. These methods are already called by the single preference implementations and therefore there should be no need to call them manually.	null	If the text is specified via a resource ID, the ID must correspond to a valid string resource.
getPositiveButton():CharSequence setPositiveButton(CharSequence):void setPositiveButton(int):void	Returns or sets the text of the positive button of the preference's dialog. If the text is null or empty, no such button will be shown. These methods are already called by the single preference implementations and therefore there should be no need to call them manually.	null	If the text is specified via a resource ID, the ID must correspond to a valid string resource.
isValueShownAsSummary():boolean showValueAsSummary(boolean):void	Returns or sets, whether the preference's current value is shown instead of its summary, or not.	false	none
isDialogHeaderShown():boolean showDialogHeader(boolean):void	Returns or sets, whether the header of the preference's dialog should be shown, or not.	false	none
getDialogHeaderBackground():Drawable setDialogHeaderBackground(Drawable):void setDialogHeaderBackground(int):void	Returns or sets the background of the header of the preference's dialog.	null	If the background is specified via a resource ID, the ID must correspond to a valid drawable resource
getDialogHeaderIcon():Drawable setDialogHeaderIcon(Drawable):void setDialogHeaderIcon(int):void	Returns or sets the icon of the header of the preference's dialog.	null	If the icon is specified via a resource ID, the ID must correspond to a valid drawable resource
isDialogButtonBarDividerShown():boolean showDialogButtonBarDivider(boolean):void	Returns or sets, whether the divider, which is located above the buttons of the preference's dialog, should be shown, or not.	false	none
areDialogDividersShownOnScroll():boolean showDialogDividersOnScroll(boolean):void	Returns or sets, whether dividers above/below scrollable content should be shown, when not fitting into the preference's dialog.	true	none
getDialogDividerColor():int setDialogDividerColor(int):void	Returns or sets the color of dividers, which are contained by the preference's dialog.	-1	none
getDialogDividerMargin():int setDialogDividerMargin(int):void	Returns or sets the left and right margin of dividers, which are contained by the preference's dialog.	0	The margin must be at least 0.
getDialogScrollableArea():ScrollableArea setDialogScrollableArea(Area):void setDialogScrollableArea(Area, Area):void	Returns or sets the scrollable area of the preference's dialog	null	When specifying two areas, the index of the second one must at least the index of the first one.
getDialogGravity():int setDialogGravity(int):void	Returns or sets the gravity of the preference's dialog.	-1	The gravity must consist of the values given in Dialog.Gravity. Multiple values can be combined by using the bitwise OR operator
getDialogWidth():int setDialogWidth(int):void	Returns or sets the width of the preference's dialog in pixels.	0	The width must be at least 1, or Dialog.MATCH_PARENT, respectively Dialog.WRAP_CONTENT
getDialogHeight():int setDialogHeight(int):void	Returns or sets the height of the preference's dialog in pixels.	0	The height must be at least 1, or Dialog.MATCH_PARENT, respectively Dialog.WRAP_CONTENT
getDialogMaxWidth():int setDialogMaxWidth(int):void	Returns or sets the maximum width of the preference's dialog in pixels.	-1	The maximum width must be at least 1, or -1, if no maximum width should be set
getDialogMaxHeight():int setDialogMaxHeight(int):void	Returns or sets the maximum height of the preference's dialog in pixels.	-1	The maximum height must be at least 1, or -1, if no maximum height should be set
getDialogMarginLeft():int getDialogMarginTop():int getDialogMarginRight():int getDialogMarginBottom():int setDialogMargin(int,int,int,int):void	Returns or sets the margin of the preference's dialog in pixels.	R.dimen.dialog_horizontal_margin as left and right padding and R.dimen.dialog_vertical_margin as top and bottom padding	All margins must be at least 0
getDialogPaddingLeft():int getDialogPaddingTop():int getDialogPaddingRight():int getDialogMarginBottom():int setDialogPadding(int,int,int,int):void	Returns or sets the padding of the preference's dialog in pixels.	R.dimen.dialog_top_padding as top padding and 0 as left, right and bottom padding	All paddings must be at least 0
isDialogFitsSystemWindowsLeft():boolean isDialogFitsSystemWindowsTop():boolean isDialogFitsSystemWindowsRight():boolean isDialogfitsSystemWindowsBottom():boolean setDialogFitsSystemWindows(boolean,boolean,,boolean,boolean):void	Returns or sets, whether the content of the preference's dialog should account for system screen decorations such as the status bar and inset its content, or not.	true, true, true, true	none

2.2 XML attributes

If a preference is created by beeing specified within a XML resource file, XML attributes can be used to customize the preference's behaviour and appearance. Besides the inherited attributes, which are defined by the Android SDK, the preference does provide various custom attributes, which can be used to set the same attributes as the setter methods already mentioned above. The custom attributes, respectively the inherited attributes, which are used by the library, are defined within the file /res/values/attrs.xml. The following table shows the attributes, all preferences, which are provided by the library, have in common.

XML attribute	Description	Format
android:dialogTitle	The title of the dialog, which is shown by the preference.	string
android:dialogMessage	The message of the dialog, which is shown by the preference.	string
android:dialogIcon	The icon of the dialog, which is shown by the preference.	reference
custom:dialogTitleColor	The color of the title of the preference's dialog.	color
custom:dialogMessageColor	The color of the message of the preference's dialog.	color
custom:dialogButtonTextColor	The text color of the buttons of the preference's dialog.	color
custom:dialogBackground	The background of the preference's dialog.	color or reference
custom:dialogWindowBackground	The window background of the preference's dialog.	reference
custom:dialogDisabledButtonTextColor	The disabled text color of the buttons of the preference's dialog.	color
custom:showValueAsSummary	Defines, whether the currently persisted value should be shown instead of the preference's summary, or not.	boolean
custom:showDialogHeader	Defines, whether the header of the preference's dialog should be shown, or not.	boolean
custom:dialogHeaderBackground	The background of the header of the preference's dialog.	color or reference
custom:dialogHeaderIcon	The icon of the header of the preference's dialog.	reference
custom:showDialogButtonBarDivider	Defines, whether the divider, which is located above the buttons of the preference's dialog, should be shown, or not.	boolean
custom:showDialogDividerOnScroll	Defines, whether dividers above/below scrollable content should be shown, when not fitting into the preference's dialog, or not.	boolean
custom:dialogButtonBarDividerColor	The color of dividers, which are contained by the preference's dialog.	color
custom:dialogButtonBarDividerMargin	The left and right margin of dividers, which are contained by the preference's dialog.	dimension
custom:dialogScrollableAreaTop custom:dialogScrollableAreaBottom	Specifies the top and bottom scrollable area of the preference's dialog.	enum
custom:dialogFullscreen	Defines, whether the preference's dialog is shown fullscreen, or not.	boolean
custom:dialogGravity	The gravity of the preference's dialog.	integer
custom:dialogWidth	The width of the preference's dialog.	dimension
custom:dialogHeight	The height of the preference's dialog.	dimension
custom:dialogMaxWidth	The maximum width of the preference's dialog.	dimension
custom:dialogMaxHeight	The maximum height of the preference's dialog.	dimension
custom:dialogMarginLeft custom:dialogMarginTop custom:dialogMarginRight custom:dialogMarginBottom	The margin of the preference's dialog.	dimension
custom:dialogFitsSystemWindowsLeft custom:dialogFitsSystemWindowsTop custom:dialogFitsSystemWindowsRight custom:dialogFitsSystemWindowsBottom	Whether the preference's dialog should account for system screen decorations such as the status bar and inset its content.	boolean

For using the custom attributes (with the prefix custom:) within a XML resource file, the following namespace has to be added to the root node of the XML file:

xmlns:custom="http://schemas.android.com/apk/res-auto"