유저 컨트롤

때때로 애플리케이션은 DG에서 제공하는 컨트롤들에 의해 우아하게 달성될 수 없는 그러한 특별한 사용자 상호작용이 필요할 수 있습니다. 그런 특별한 경우에는 모든 요구사항을 완벽하게 충족하는 당신만의 컨트롤을 개발할 수 있습니다. 이러한 타입의 컨트롤을 DG에서는 "유저 컨트롤"이라고 합니다.

예를 들면, 사용자가 다이얼로그의 미리 정의된 색상 팔레트에서 특정 색상을 선택해야 한다고 가정합니다. 이 작업은 리스트 박스 또는 팝업 컨트롤로 해결할 수 있지만 다음 유저 컨트롤이 최선의 해결책일 수 있습니다. 사용자가 현재 선택된 색상을 표시하는 버튼 모양의 컨트롤을 누르면, 키 누름 또는 마우스 클릭으로 새로운 색상을 선택할 수 있는 팝업 팔레트가 나타납니다.

유저 컨트롤은 범위 및 현재 값을 갖습니다. 범위는 컨트롤이 나타낼 수 있는 연속 값들의 집합입니다. 이러한 값은 short integer로 표현되기 때문에 가능한 최소값과 최대값은 각각 SHRT_MIN과 SHRT_MAX입니다. 유저 컨트롤은 3가지 타입의 DG 메시지만 보낼 수 있으며(메시지 참조), 유저 컨트롤의 제어 지정 데이터를 설정하거나 가져오는 함수 쌍은 단 한 개뿐입니다.

유저 컨트롤들은 DG에 용이하게 통합될 수 있습니다. 그것들은 GRC에서 또는 DGAppendDialogItem에 의해 프로그램 코드에서 모두 생성될 수 있습니다. 당신이 유저 컨트롤을 쓸 때는 몇 가지 규칙만 유지해야 한다. (설명 참조)

항목 타입

DG_ITM_USERCONTROL

GRC 사양

    UserControl    x  y  dx  dy  cdefID
                   [data1  ...  datai  ...  datan]

여기서 x와 y는 유저 컨트롤의 좌상단 모서리의 픽셀 좌표이고, dx와 dy는 컨트롤의 폭과 높이의 픽셀 크기입니다. cdefID는 컨트롤 정의 프로시저 ID입니다. (범위 512 <= ldefID <= 999 안에 있어야 함) 선택적 datai (1 <= i <= n) short 파라미터는 유저 컨트롤(n은 0일 수 있음)을 초기화할 수도 있습니다. 이러한 파라미터들은 10진수 또는 16진수 형식으로 모두 제공될 수 있으며 더 많은 라인으로 작성할 수 있습니다.

메시지

메시지	의미
`DG_MSG_CHANGE`	유저 컨트롤의 값이 변경되었습니다. 메시지 데이터 파라미터는 이전 값을 포함하고 있습니다.
`DG_MSG_DOUBLECLICK`	사용자 컨트롤을 더블 클릭했습니다. 메시지 데이터 파라미터는 항상 0입니다.
`DG_MSG_TRACK`	유저 컨트롤의 값이 추적하는 동안 변경되었습니다. 메시지 데이터 파라미터는 서브-메시지입니다.

수정 Flag

DGSetItemValLong, DGSetItemMinLong, DGSetItemMaxLong 함수들은 다이얼로그 콜백 함수에서 DG_MSG_INIT 메시지를 처리할 때 호출되는 경우를 제외하고는 유저 컨트롤의 수정 flag를 설정할 수 있습니다. Flag는 또한 DG_MSG_CHANGE 또는 DG_MSG_TRACK 메시지를 생성하는 사용자 동작에 의해 설정될 수 있습니다. 수정 flag의 상태를 가져오거나 리셋(지우기)하려면 DGModified 또는 DGResetModified를 사용하십시오.

설명

유저 컨트롤의 값 및 범위는 GRC의 datai 파라미터에 의해 초기화될 수 있습니다. 나중에 DGSetItemMinLong과 DGSetItemMaxLong 함수를 사용하여 범위를 동적으로 변경할 수 있습니다. 가능한 최소 범위는 SHRT_MIN이고 최대 범위는 SHRT_MAX입니다. DGGetItemMinLong과 DGGetItemMaxLong을 사용하여 유저 컨트롤 범위를 가져오십시오. 유저 컨트롤의 현재 값은 DGSetItemValLong과 DGGetItemValLong에 의해 각각 설정하고 가져올 수 있습니다.

만약 범위 또는 값 설정 함수 중 하나를 호출하면 DG는 데이터의 일관성을 확인합니다. (즉, minimum <= value <= maximum 조건이 참인지 아닌지) 만약 데이터가 일관성이 없으면 DG가 자동으로 조정합니다. 이 조정에 대한 자세한 내용은 DGSetItemValLong, DGSetItemMinLong, DGSetItemMaxLong을 참조하십시오.

유저 컨트롤은 값과 범위 외에도 시각적 외형과 컨트롤의 동작을 설명하는 데이터 블록을 가질 수 있습니다. 또한, 애플리케이션은 이 블록에 다른 정보를 저장할 수 있습니다. 이러한 제어 지정 데이터는 GRC에서 초기화할 수 있으며 DGSetItemData와 DGGetItemData 함수에 의해 프로그램 코드에서 액세스할 수 있습니다. 그러나 이러한 함수들은 버전 DGLib 2.2.0에서 제외됩니다. 왜냐하면 UC 모듈에서 미리 선언된 유저 컨트롤은 모두 설정을 변경하기 위한 자체 인터페이스를 가지고 있기 때문입니다.

사용자 동작의 결과로 유저 컨트롤은 3가지 타입의 DG 메시지를 보낼 수 있지만 3가지 메시지를 모두 지원할 필요는 없습니다. 그것은 어떤 메시지가 그것에 의해 지원되는지 컨트롤의 특성에 달려 있습니다. 만약 유저 컨트롤이 추적을 지원하고, 사용자가 컨트롤 클릭하고 추적하면, DG는 사용자가 (왼쪽) 마우스 버튼을 뗄 때까지 DG_MSG_TRACK 메시지를 다이얼로그 콜백 함수로 보냅니다. DG_MSG_TRACK 메시지로 서브-메시지도 전달됩니다. 여기서 서브-메시지는 유저 컨트롤 이벤트를 더 상세하게 지정합니다. 이렇게 하면 애플리케이션이 추적 중에 다른 컨트롤을 변경할 수 있습니다. DG_MSG_TRACK 메시지를 처리할 때 DGGetItemValLong을 호출하여 컨트롤의 현재 값을 가져오십시오. 추적이 끝나자마자 콜백 함수는 DG_MSG_CHANGE 메시지를 수신합니다; 메시지 데이터 파라미터는 추적하기 전에 컨트롤 값입니다.

유저 컨트롤을 위해 많은 작업들이 DG에 의해 내부적으로 처리됩니다. (보이기, 숨기기, 크기, 이동 등) 그러나 다른 많은 작업은 컨트롤 자체에 의해 구현되어야 합니다. (업데이팅, 그리기, 사용자 작업 처리하기 등)

Mac logo Macintosh 전용:

Macintosh에서 만약 당신이 유저 컨트롤이 필요한 경우, 표준 컨트롤 정의 프로시저를 작성하여 애플리케이션의 리소스 fork에 배치합니다. CDEF 리소스는 GRC의 cdefID 파라미터 또는 DGAppendDialogItem의 itemData 파라미터에 의해 주어진 인덱스를 가져야 합니다. 컨트롤은 다음 Macintosh API 함수 호출들을 지원해야 합니다: SetControlValue, GetControlValue, SetControlMinimum, GetControlMinimum, SetControlMaximum, GetControlMaximum, SetControlData, GetControlData. (자세한 내용은 Macintosh API 문서를 보십시오)

Windows logo Windows 전용:

Windows에서는 상황이 좀 더 복잡합니다. 먼저 애플리케이션은 "CDEFXXX"라는 이름으로 자체 창 클래스를 등록해야 합니다. 여기서 "XXX"는 컨트롤 정의 프로시저 ID의 세 자리 숫자를 나타냅니다. DG와 통신하기 위해서는 유저 컨트롤이 창 프로시저에서 일부 DG 지정 컨트롤 메시지에 응답해야 합니다. 이러한 메시지, 파라미터, 리턴 값 및 DG가 전송하는 함수들은 다음 표에 요약되어 있습니다.

메시지	wParam	lParam	리턴 값	함수
`DG_CM_SETMIN`	1	컨트롤 최소	사용하지 않음	DGSetItemMinLong
`DG_CM_GETMIN`	0	0	컨트롤 최소	DGGetItemMinLong
`DG_CM_SETMAX`	1	컨트롤 최대	사용하지 않음	DGGetItemMaxLong
`DG_CM_GETMAX`	0	0	컨트롤 최대	DGGetItemMaxLong
`DG_CM_SETVAL`	1	컨트롤 값	사용하지 않음	DGSetItemValLong
`DG_CM_GETVAL`	0	0	컨트롤 값	DGGetItemValLong
`DG_CM_SETDATA`	데이터 블록 크기 (바이트 수)	데이터 블록에 대한 포인터 (NULL이 될 수 없음)	만약 오류가 발생하면 -1, 그 외에는 0	DGSetItemData
`DG_CM_GETDATA`	데이터 블록 크기 (바이트 수)	데이터 블록에 대한 포인터 (NULL이 될 수 있음)	전체 컨트롤 데이터의 크기 (바이트 수)	DGGetItemData

DG_CM_SETDATA 메시지에 대한 참고:

만약 wParam이 컨트롤의 데이터 블록의 현재 크기보다 크면, 컨트롤은 새로운 데이터를 위한 공간을 만들기 위해 메모리 블록을 증가시켜야 합니다.
만약 wParam이 컨트롤의 데이터 블록의 현재 크기보다 작으면, 컨트롤은 데이터 블록의 첫 번째 wParam 바이트만 업데이트해야 합니다.
컨트롤은 오류가 발생하면 -1, 그 외에는 0을 리턴해야 합니다.

DG_CM_GETDATA 메시지에 대한 참고:

만약 lParam이 0이 아니고, wParam이 컨트롤의 데이터 블록의 현재 크기보다 작으면, 컨트롤은 첫 번째 wParam 바이트만 lParam 버퍼로 복사해야 합니다.
만약 lParam이 0이면, 컨트롤은 데이터 블록의 크기를 리턴해야 합니다.

사용자 액션에 의해 유저 컨트롤의 현재 값이 변경되면, 컨트롤은 SendMessage Windows API 함수를 사용하여 DG 지정 알림 메시지들을 부모 대화상자로 전송해야 합니다. DG는 이러한 알림을 표준 DG 메시지로 번역한 다음, 다이얼로그 콜백 함수로 보냅니다. 다음 표에는 알림 메시지, 파라미터 및 해당 DG 메시지들이 포함되어 있습니다:

알림	wParam	lParam	DG 메시지
`DG_CN_CHANGE`	컨트롤의 1-기반 인덱스	컨트롤의 이전 값	`DG_MSG_CHANGE`
`DG_CN_TRACK`	컨트롤의 1-기반 인덱스	사용하지 않음	`DG_MSG_TRACK`

만약 유저 컨트롤이 추적을 지원하고 사용자가 컨트롤을 클릭하고 추적하는 경우, DG_CN_TRACK 알림 메시지는 사용자가 (왼쪽) 마우스 버튼을 해제할 때까지 부모 다이얼로그로 전송되어야 합니다. 만약 추적이 완료되고 컨트롤의 현재 값이 추적 전의 값과 다른 경우, 컨트롤은 DG_CN_CHANGE 알림도 보내야 합니다.

DG 지정 컨트롤 메시지들 외에도 모든 메시지는 컨트롤의 창 프로시저에서 처리할 수 있습니다. 처리되지 않은 메시지들은 기본 창 프로시저로 전달되어야 합니다.

요구사항

버전: DG 2.0.0 또는 이후

헤더: DG.h

참고사항

다이얼로그 항목 타입, 리스트 박스, 팝업 컨트롤
DGAppendDialogItem, DGGetItemData, DGGetItemMaxLong, DGGetItemMinLong, DGGetItemValLong, DGModified, DGResetModified, DGSetItemData, DGSetItemMaxLong, DGSetItemMinLong, DGSetItemValLong, 콜백 함수
DG 메시지, DG_MSG_CHANGE, DG_MSG_DOUBLECLICK, DG_MSG_INIT, DG_MSG_TRACK