MIDI Mapper Control Panel Applet Mike McQueen (t-mikemc) 1-Oct-90
--------------------------------
Hastily updated by LaurieGr
This document describes how the MIDI Mapper applet was put together, in
order to hopefully make it easier for someone other than myself to find
and fix any bugs or change some features.
Currently the source for this applet is divided into seven modules,
four header files and a resource script file.
Descrption of MIDI Mapper applet:
================================
Modules
-------
LIBINIT.ASM
Contains the LibEntry function. This piece of code sends shivers
up my spine every time I look at it. Someone (other than ToddLa)
really ought to make a nice clean standard DLL entry point asm
module. Doesn't apply to NT.
MIDI.C
Contains the LibMain and WEP functions for windows.
Contains the CPlApplet export function for multimedia control panel.
This is the entry point that the controlpanel calls.
Start debugging here!
Contains the 'MIDI Mapper' dialog box function. Among other things,
this dialog box has three combo boxes into which the available setups,
patchmaps and keymaps are respectively enumerated. When someone
deletes a map, it's not actually deleted from the file, but rather
its entry is simply removed from the combo box. If the guy then
clicks on the 'OK' button, interpreted as 'OK, go ahead and actually
delete the maps', I compare the available maps to the maps left
in the combo boxes, and delete any discrepancies. This is done in
the EnumFunc function described below.
This module also contains several functions that are used by one or
more of the map editing modules. I probably should have thrown
together a 'MISC.C' module and tossed all these functions in there,
but in any case all these functions are at the bottom of the file.
The WriteBoxRect and SizeBox functions were only used in the version
of the applet that allowed sizing of map-editing boxes. If sizing
is never ever going to be used, these can be removed.
**EnumFunc**
This lovely little treat of a function is the callback for the
mapEnumerate function from midimap.c in the MMSYSTEM DLL. it is used
by calls to mapEnumerate from 3 different modules, MIDI.C, SETUP.C
and PATCH.C.
mapEnumerate is called to enumerate Setups, Maps, Patches or ports
which don't have an awful lot in common. It's also called from
all over the place. The price for having only one copy of the 16
statements that actually do the enumeration is that all the different
callback functions are forced into the same straightjacket of
parameters. On 16 bit it inevitably had a handle packed into half
a DWORD. The callback which is executed once for each element now
has three parameters to cater for all cases (with a little casting)
and some subset of these are actually used in each case.
The SETUP.C and PATCH.C modules simply call it to enumerate the
available patchmaps and keymaps into their combo boxes, respectively.
In MIDI.C, the HIWORD of the dwUser parameter is either set to
MMENUM_DELETE, MMENUM_BASIC or MMENUM_INTOCOMBO.
If it is set to MMENUM_INTOCOMBO, it indicates that this enumeration
is taking place into the combo box of the MIDI Mapper dialog box.
When this happens, a handle is allocated for the length of the
description string, and this handle is set to be the new combo box
entry's ITEMDATA. This is how I update the description when the user
changes the current selection in the combo box in the main dialog.
If it is set to MMENUM_DELETE, it indicates that a check is being done
to see if any entrys in the combo box differ from the available maps
being enumerated. In this case, if a map name is sent to EnumFunc
from mapEnumerate, and it does not exist in the combo box, it will be
deleted right then and there with a call to mapDelete (another
midimap.c function).
SETUP.C
PATCH.C
KEY.C
These modules are pretty similar in content, so I am going to try to
describe them all in one plop. A lot of the functions from these
three modules have the same name, but are prefixed with 'Setup',
'Patch' or 'Key' depending on which module they are in. I'm going to
use 'xxx' to mean any or all of those three prefixes.
The 'xxxBox' functions are the three dialog box functions for the
three map-editing dialog boxes.
The 'xxxPaint' functions are the only places where anything is ever
drawn on the screen. These functions are essentially the BeginPaint
EndPaint blocks for each map editor.
In the setup editor, I do a funny little trick to allow tabbing onto
three-state buttons, and it would probably be a good idea to explain
it. Every time SetupSetFocus is called, I remove the WS_TABSTOP style
attribute from the 3-state button on the last edit line, and add it
to the 3-state button on the new edit line. I also change the text to
"&A" which allows the ALT-A accelerator to work.
Global variables which pertain to all three of these modules are
described under the 'extern.h' header file.
PROPBOX.C
Contains only a dialog box function for getting properties for a new
map of any type. If the 'fSaveAs' variable is set, it will
automagically check for duplicate names. Unfortunately, I don't have
any way of doing a 'save as...' in the current version. If you think
of a way, you could just call this dialog box with the fSaveAs
variable set.
CPARROW.C
Contains a routine for registering a window class for a control panel
arrow control, as well as the window function for that class. There
is a arrow in WINCOM, and there is another arrow in SCRNSVR (that's
where I stole this code from). I think my version works/looks better
than both of the others. I also think it still needs to be worked
on. I think that if and when this ever gets done, it should go in
WINCOM and then the static link modules could go away.
Headers
-------
MIDI.H
Contains all sorts of definitions, and I've tried to document them
as best as possible.
PRECLUDE.H
Contains 'preclude' definitions for windows.h and mmsystem.h, to
make compiling a little faster.
CPARROW.H
Contains the prototypes for the arrow class (un)registering functions.
EXTERN.H
Contains external variable definitions, with limited comments. I'll
comment them again right here:
extern HWND hWnd // 'Current' window handle
hEdit, // Edit control handle
hArrow; // Arrow control handle
extern RECT rcBox; // Clipping/scroll rectangle
extern int rgxPos [8], // horizontal line positions
yBox, // rows of data y extent
xClient, // Window client area x pixels
yClient, // Window client area y pixels
iCurPos, // Current position on screen
iVertPos, // Current vertical scroll position
iVertMax, // Maximum veritcal scroll position
nLines, // Number of lines of data
yChar, // Height of character in font
xChar, // Width of average character in font
iMap; // Flag for GetMBData
extern char szCurrent [], // Name of current map
szCurDesc [], // Description of current map
szMidiCtl [], // "MIDI Control Panel"
szNone []; // Static text string '[ None ]'
extern BOOL fModified, // Has map been modified?
fNew, // Is this a new map?
fSaveAs, // Is propbox being used for Save As?
fHidden; // Is the active edit line hidden?
Resource script
---------------
midi.rc
Problems with MIDI Mapper applet:
================================
Currently, the maximum number of any type of map (setup,patchmap,keymap) is
limited to 100. This is a deficiency in midimap routines which are part of
mmsystem. If someone calls the mapWrite function with the flag set to the
type of a map of which there are 100, the write will fail. The only way to
currently get around this problem is deleting maps.
In the process of changing the current selection of either the "Keymap Name"
combobox in the Patchmap editor, or the "Patchmap Name" combobox in the Setup
editor, memory is potentially being reallocated without fail checks, which
means it should be possible to run out of memory in a bad way if the current
selection of these comboboxes is changed a lot.
For the patchmap editor, all keymaps are the
same size. I should never have to reallocate the whole setup just so it turns
out to be the exact same size! Anyway, the problem arises when you have a
patchmap with some keymaps. Someone derefernces a keymap from a specific
patch number in the patchmap editor (that is, selects the [none] entry for
that particular patch). This in turns causes the keymap offset of that
patchmap to be set to zero. If the person proceeds to re-reference that
patchmap back to the same keymap, or any other keymap, the entire setup will
be reallocated, to the same size. Although this will call will probably never
fail, it is unnecessary.
A flag lying around in the patchmap structure which indicates that the memory
for a keymap has been allocated make this very useful. Perhaps it would be a
good idea to define a range of flags in the dwFlags structure entry of the
MIDIKEYMAP/MIDIPATCHMAP/MIDIMAP data structures which are for internal use
only, some reserved bits.
The formula for the size of the new setup is <old setupsize> + <new patchsize>,
which does not take into account subtracting <old patchsize>. The reason for
this is that the patchmap may be referenced by other channels in the setup.
You cannot free the memory of the patchmap just because one channel doesn't
reference it anymore. The thing is, it would be really easy to check and see
if anyother channel references it. There are two APIs called:
mapPatchMapInSetup and..
mapKeyMapInPatchMap
which are exported from mmsystem. These routines should be used by the
SetupComboMsg
function, under the CBN_SELCHANGE message. It is here that the existence
of any given patchmap name in the current setup can be determined by calls
to the former API. It is not necessary to reallocate an entire setup if
one channel in that setup suddenly references a patchmap that is already
referenced in that setup. All that should happen is the new channel's
patchmap offset value should be set to that of the existing channel. In a
similar instance, if a patchmap is dereferenced by a channel of a setup, and
it is determined that no other channels of that setup use that patchmap, the
size of that patchmap may be subtracted from the setup reallocation size.
f7ca35dddd