Pimlical/Android Widget

Pimlical Android Widget Settings

The Pimlical Widget is now an integral part of the Pimlical Calendar Application. This is a new, subscription-only feature. The old standalone widget does not work with V-4.0 as it does not use scoped storage, nor does it cater to the new functionality in V-4.0.

Installing the Widget

The Widget installs in the same manner as any other Android Widget. Before installing though, make sure that you launch Pimlical/Android and make sure that it is left in a main view (i.e. do not open up a dialog and then switch to the home screen with the dialog left on the screen!). Then long-press an empty spot on a home screen, select WIDGETS from the popup menu, navigate to PimlicalA and drag the Pimlical Widget onto the home screen. At that point, the Widget Settings screen appears where you can configure the widget.

This Settings screen allows you to configure some of the attributes for the widget. This configuration screen displays on installation of the widget, or when the Pimlical logo (at top left) is tapped. This widget will work with both the standard Android calendar as well as Pimlico Software's local calendar. For more Information on Pimlical/Android - a Personal Information Manager that supports advanced calendar functions as well as a local contacts and memos database on both Android and Windows Desktops, see www.pimlicosoftware.com

The Settings dialog displays the current version of the Widget in the title bar of the dialog (in the example above, the version is 3.7.01).

The attributes you can set are:

Refresh interval

This setting determines how often the widget re-reads the calendar. The widget only refreshes when the device is powered on, so setting a short interval of 15 minutes or so should not impact battery usage significantly (the Android OS imposes an absolute lower limit of 15 minutes for the refresh interval). When refreshing pimlical will read all the currently selected Android calendars as well as Pimlical/Android's local calendar (if present). You can actually set any value you like for this item by going into P/A and adjusting the Preference: WidgetRefreshInterval. Note that with more recent versions of the Android OS, you must disable battery optimization as otherwise no background tasks can be run by the app (in which case the Widget won't be able to refresh itself). This setting is in the Android OS System Settings (and you should be aware of this issue as it affects all Android apps that need to run a background task). Note too, that you cannot make changes or view calendar items in P/A while the Widget is refreshing, so setting a brief period like 15m might interfere with your use of Pimlical.

Text Rows

The widget can display from 1 to 25 text rows (one text row for each event/task) depending on the available space. The default setting is Auto which attempts to calculate a reasonable number of rows for the display. It is quite likely that you will want to set a precise value which is optimal for your particular device - in that case, tap OK and look at the widget to see how many text rows would fit (don't forget that there is a row at the bottom for the next, upcoming alarm). Then tap the Pimlical logo and this time use the dropdown list to set the optimal number of rows for the display. The widget is resizable (after tapping OK in the Settings screen, long-press the widget and resize handles will appear that allow you to resize the widget both horizontally and vertically). Some Android devices, (such as Samsung) have proprietary code in the Android OS and may require a fixed setting. If you have the number of rows set to Auto and the size does not appear to be correct on installation, try tap&hold (which invokes resize handles) and release (some Samsung devices then report the correct size and will expand to fill the space). If that fails to set the correct number of text rows, pick an appropriate, explicit value from the dropdown list.

The count of text rows does not include the top date line, nor the next alarm line at the bottom, but does include all the lines inbetween (including the lines that just have dates on them). There will be cases where a blank line appears at the end, because the next item is on a different day, and there isn't room to include the Date line and the first event on that day.

Note: if you don't see the Alarm Line at the bottom of the widget, this is because you have too many rows displaying. Count the number of rows excluding that last row and then set that as the number of rows to use and you will then see the Alarm line.

Transparency

This setting controls the transparency of the background of the widget. A value of 0 is totally opaque, while 100 would be totally transparent. You can adjust the transparency either by moving the slider, or tapping the button and keying in an exact value. Some Android devices don't handle transparency properly due to failure to properly implement the Android OS and instead just display an opaque background. There is no workaround for this issue at this time.

Typesize

This dropdown list sets the typesize for the text displayed in the widget. Whatever size you pick is used for the description fields. The date line at top and alarm line at bottom are scaled to approximately 110% of whatever value you pick for the description lines. if you use a typesize of 12 or less, the full date is displayed (Monday, January 1, 2016). If you pick 13 or 14, only the first three letters of the day of week and month are displayed (Mon, Jan 1 2016). If 16/18/20, then the date is displayed in medium format (1/1/2016) and if a fontsize larger than 24 is selected, then only the month and day are displayed (1/1).

On some devices, the width available for displaying the date is not always correct in which case you might see a short version of the date used when there's clearly enough room to display the long form of the date. In that case, you can use the preference: WidgetDateWidth to force the Widget to fit the date to that width in pixels (so if you set that preference to 600, that would mean that P/A can assume a width of 600 pixels for displaying the date field). You might have to find the appropriate value by trial and error, although you can make a good guess if you know the width of your screen in pixels (see DisplaySize line in menu | About).

12 Hour Clock

Check this box to display times in 12 hour format with am/pm indicator. Uncheck the box to display times in 24-hour format.

White Text

By default, Pimlical displays all the text with black type. Check this box to use white for the type instead - this may work better when using a transparent background over a dark graphic.

Show Quick Entry Template Button [Q]

The widget can optionally display a button that will invoke Pimlical's Template Dialog, so you can enter a new event by using a Pimlical/Android Template. By default, this button is not displayed.

Hide All Top Row Widget Buttons

If this checkbox is checked, all the top row buttons in the Widget are hidden. To restore those buttons, you will of course have to remove and reinstall the Widget as the only way to get to the configuration screen otherwise is to use the logo button (which this option hides!). This option may be useful to some users who want as much space as possible for the calendar and don't care about the launch functionality available in the widget itself.

Use Event/Category Colors

If this checkbox is checked, the text color for the event will be taken from the event's custom text color (if it has one), or if not, from the category that the event is in. If the foreground text color is the default color (i.e. pure black), and the background is not the default background color (Pure White), then the background color will be used for the text color of the event.

Settings Buttons

The Done button applies all the current settings and launches the Widget (to just VIEW the current configuration settings without launching the widget, see Exit button below).

The Reset button resets all the settings back to the way they were when you invoked the Settings dialog, use this if you want to exit the Settings dialog without changing anything, as it will discard any unsaved changes that you might have made.

The Info button brings up this help file that you are now reading. You can also use this button as a way to exit out of the Configuration dialog without invoking a refresh on the widget.

A small Exit button appears near the bottom of the dialog after the widget has been installed and the Pimlical Icon is tapped (to change the configuration settings). This button will exit the configuration dialog without triggering an automatic refresh of the Widget. It appears just below the date and time of the last Widget Refresh and, if there was a problem, the reason why the refresh did not take place (typically to avoid some problem interaction with PImlical/Android).

Other Settings

The selection of events to display in the widget is actually controlled by a Pimlical Filter with the name Widget. If you have Pimlical/Android calendar installed, you can edit the filter to basically filter events in any way that you want. For example, by default the filter only includes future timed events, but you can easily change the filter to include untimed events, only include events in certain calendars or categories in the local calendar, etc. If you have Pimlical Local calendar installed, you can also choose to hide floating events and/or tasks in the widget display, or hide or display the text of private events (private events are normally masked). Or perhaps you prefer to see only floating events and tasks that are currently due and not those that are due in the future.

For even more control, you can check the box in the Repeat Tab of the Filter/Edit dialog to indicate that the Widget filter has a custom preference file - with that, the widget can have its own set of preferences completely separate from those used in Pimlical/Android (for example, you could set up Pimlical/Android to use the Short Description feature, but not use that in the widget itself, or you could hide all alarms in the Widget, but still have them display in Pimlical/Android). You may wish to do this if you are an advanced user and using custom preference files attached to filters which potentially modify the default preference settings (if you do that, the Widget will use the default preferences, and might end up displaying something different from what you expect).

By default, the widget will attempt to use the ShortDescription field of an event rather than the full description. To avoid this behavior, set the preference UseShortDescriptions to false. Note, however that will also restrict the use of Short Descriptions in P/A as well since you are changing the Default Preferences. If you want to change the behavior for the Widget only, then edit the Widget filter and go the last tab on the second line (Repeat Rule and View) and check the box SAVE CUSTOM PREFERENCES WITH FILTER and tap OK. Then tap on the Widget filter, which will then also invoke the custom preference file for the widget (Widget.txt, Widget.data and backups etc.). Then change the preference: UseShortDescriptions to false. That way you can still use short descriptions in P/A but avoid them in the Widget display.

Default Widget Filter Settings

Only future Items are displayed
Exclude canceled Items
Exclude completed Items
Exclude deferred items (from P/D only at this time)
Only timed events are included (Untimed/AllDay excluded)
Set date to FIXED, actual starting date does not matter, what matter is the DATE RANGE:
Date Range = up to 31 days into the future (Set the End date X days after the Start date, where X is the number of days you want to display in the Widget.

All these settings can be modified by editing the Widget filter in Pimlical/Android. And by checking the box to save a custom preference file with the filter (as indicated above for handling Short Descriptions) you can make custom changes to any Pimlical preference and have them only apply to the widget and not other filters in P/A (such as P/A's Default filter).

The Widget Display

The widget displays up to six buttons on the top row:

Tap this button to display the Settings Screen. To the right of this button in very small type is the time that the display was last refreshed (can be useful in diagnosing any hiccough in Android that might have caused the Widget to stop refreshing itself).

Tap this button to force an immediate refresh of the calendar. The refresh interval you have selected is then reset to the current time (so if you are refreshing every ten minutes, the next refresh after this one will be in ten minutes).

Tap this button to create a new event in the calendar. If you are not using Pimlical/Android's calendar, this function may only launch the calendar and not necessarily open the calendar with a new event created. To view the calendar, just tap anywhere on the widget below the Date Line (the first line below the button row).

Tap this button to create a new event in the calendar from a Template. The widget launches Pimlical/Android and displays the template list so you can select the template to insert. This button requires Pimlical/Android as there is no equivalent functionality in other calendar applications. This button is only displayed if you check the corresponding checkbox in the Settings Dialog.

Tap this button to launch the contacts application. If Pimlical/Android is installed, this will launch the Pimlical Contacts application, otherwise it will launch any contacts application that you have installed on your Android device which responds to standard Android requests.

If displayed, tap this button to launch the Pimlical Memos application. This button is not displayed if you do not have Pimlical/Android installed or did not create a local memos database.

Appointment Information

Below the button row, Pimlical displays the date and time of the first appointment displayed on the line immediately below. Normally, this will be the next appointment scheduled for today. By default, Pimlical only displays up-coming appointments in the widget (or an appointment that is still in progress), although this can be changed by editing the Widget filter in Pimlical/Android. Pimlical may display a system icon (float, task, completed, canceled, etc.) followed by the first icon associated with the event (if any).

After this icon, Pimlical displays how much time there is until the next, scheduled appointment. If nothing is displayed, this means that the appointment on the top row of the widget is still in progress. A display like 1h 45m would mean that the next appointment is scheduled for one hour and 45 minutes from the present time. So this figure basically tells you how much free time you have before the next appointment. Note that this only applies to events that are being displayed in the widget - if an event is hidden in the widget (but displayed in the calendar) it will not be taken into consideration.

Appointments are listed in the following rows in the widget. If an icon has been assigned to the item in Pimlical/Android, that will appear between the time and description field. If the appointment has a custom font set in Pimlical/Android, then the description field will be displayed in bold type for emphasis. Private events are normally masked by Pimlical/Android and will only display the legend Private. By editing the Widget filter in Pimlical/Android, you can change that behavior to either completely hide private events, or to display all the text in the widget.

Tap on any text row below the top row to launch the Calendar application. if you have the Pimlical/Android calendar installed, it will launch Pimlical Calendar. Otherwise, it will launch any calendar application that you have installed on your Android device that responds to standard Android requests.

The final line of the widget displays the next, upcoming alarm that is set in the calendar. Note that the event for which the upcoming alarm is displayed may not necessarily be for an event that is displayed in the widget (if your widget settings are hiding the event that has the next alarm set). If the next alarm was a snoozed alarm, [Z] is displayed after the time.

Trouble-Shooting

If you run into problems with the widget (especially if you were making extensive modifications to the Widget filter, etc.), you can always get back to a known good condition with this procedure:

Uninstall the widget from the home screen.
If you have Pimlical/Android, go into menu | Filters and delete the Widget filter.
Reboot your phone (this ensures that no background service is unexpectedly left running). If skipping this, Force-Stop P/A.
Launch Pimlical/Android.
Re-install the widget.

That should reset everything to a known good condition for you. If you are still experiencing any problems, contact Technical Support for Assistance.

However, if the only problem you are seeing is that the widget is not refreshing, by far the most likely issue is that you have not disabled "battery optimization" for the Widget - and until you do that, the Widget is denied the ability to run the background task necessary to refresh the screen. The 'battery optimization' setting is in the Android System Settings section for your device. On some devices, this setting is automatically reset on a re-install, so double-check that (and make that a Step 6. in the above procedure to do that). In App battery usage in Android system settings, we recommend setting Unrestricted if you are seeing issues with the Widget not refreshing for no apparent reason. In theory, the Optimized setting should work, but it's undocumented exactly what the Android OS does in this case. If set to Restricted, the widget will definitely fail to work properly.

Also, for a detailed revision history of every change made to the Pimlical/Android Widget, you can click here..

Visit the Pimlico Software website at www.PimlicoSoftware.com for further information about the advanced calendar/PIM: Pimlical/Android and the new Pimlical Widget. There is a matching windows desktop application along with DirectSync, so you can use Google Calendars and/or a completely secure local calendar that syncs "off-cloud" for complete security.

Last Revised:22Jan2016