유저 아이템

유저 아이템은 다음 이중 성격을 가진 DG의 특수 타입 다이얼로그 항목입니다:

• 유저 아이템은 아무 텍스트, 이미지, 라인 드로잉을 표시할 수 있습니다. 이러한 측면에서 정적 텍스트, 아이콘 및 그림 항목들과 비슷합니다. 그러나 드로잉 영역은 위에서 언급한 다이얼로그 항목들보다 더 복잡한 정보를 표시하는 데 사용할 수 있습니다.
• 반면에, 유저 아이템은 대화식 다이얼로그 항목이므로 유저 컨트롤과도 비슷합니다. 만약 애플리케이션 여러 다이얼로그에서 동일한 특수 사용자 상호작용을 필요로 하는 경우, 작업을 해결하기 위해 유저 컨트롤을 개발하는 것이 좋습니다. 그러나 하나의 다이얼로그에서만 특별한 다이얼로그 항목이 필요하거나, 항목의 내용이 매우 풍부하고 컨텍스트에 민감해야 하는 경우 유저 아이템이 가장 좋은 솔루션인 것으로 보입니다.

업데이트가 필요할 때마다 유저 아이템을 그리는 것은 애플리케이션의 책임입니다. 기본적으로 유저 아이템은 프레임 없이 그리지만 3가지 타입의 프레임을 가질 수 있습니다: static edge, client edge and modal frame. 다음 이미지는 client edge 프레임을 가진 유저 아이템을 보여줍니다.

항목 타입

DG_ITM_USERITEM

서브 타입

서브 타입	의미
DG_UT_NORMALUPDATE	유저 아이템은 DG_UUT_NORMAL 업데이트 타입만 사용하여 DG_MSG_UPDATE 메시지를 수신합니다.
DG_UT_PARTIALUPDATE	유저 아이템은 DG_UUT_NORMAL과 DG_UUT_PARTIAL 업데이터 타입을 사용하여 DG_MSG_UPDATE 메시지를 수신합니다.

프레임 타입

프레임 타입	의미
DG_FT_NONE	프레임 없이 그려집니다.
DG_FT_STATIC	함몰 모서리를 가진 얇은 3차원 경계입니다.
DG_FT_CLIENT	함몰 모서리를 가진 두꺼운 3차원 경계입니다.
DG_FT_MODAL	돌출 모서리를 가진 두꺼운 3차원 경계입니다.

GRC 사양

    UserItem    x  y  dx  dy  [PartialUpdate]  [frameType]

여기서 x와 y는 유저 아이템의 좌상단 모서리의 픽셀 좌표이고, dx와 dy는 항목의 폭과 높이의 픽셀 크기입니다. 부분 업데이트를 사용하기 위해 선택적 PartialUpdate flag를 세트합니다. 만약 선택적 frameType flag가 생략되면, 유저 아이템은 프레임 없이 그려집니다.

frameType의 가능한 값은 다음과 같습니다:

값	의미
Default	DG_FT_NONE 프레임 타입이 세트됩니다.
StaticEdge	DG_FT_STATIC 프레임 타입이 세트됩니다.
ClientEdge	DG_FT_CLIENT 프레임 타입이 세트됩니다.
ModalFrame	DG_FT_MODAL 프레임 타입이 세트됩니다.

메시지

메시지	의미
DG_MSG_CLICK	유저 아이템을 클릭했습니다. 메시지 데이터 파라미터는 DGMessageData로 캐스팅된 DGUserMsgData structure에 대한 포인터입니다. 이 structure에는 사용자 작업에 대한 정보가 들어 있습니다.
DG_MSG_DOUBLECLICK	유저 아이템을 더블 클릭했습니다. 메시지 데이터 파라미터는 DGMessageData로 캐스팅된 DGUserMsgData structure에 대한 포인터입니다. 이 structure에는 사용자 작업에 대한 정보가 들어 있습니다.
DG_MSG_MOUSEMOVE	마우스가 유저 아이템 위에 있습니다. 메시지 데이터 파라미터는 DGMessageData로 캐스팅된 DGUserMsgData structure에 대한 포인터입니다. 이 structure에는 사용자 작업에 대한 정보가 들어 있습니다.
DG_MSG_UPDATE	유저 아이템은 완전히 혹은 부분적으로 다시 그려져야 합니다. 사용자 업데이트 데이터 파라미터는 DGMessageData로 캐스팅된 DGUserUpdateData structure에 대한 포인터입니다. 이 structure는 애플리케이션이 유저 아이템을 업데이트하기 위해 필요한 모든 정보를 포함하고 있습니다.
DG_MSG_DRAGDROP	드래그 앤 드롭 관련 이벤트가 발생했습니다. 유저 아이템들은 드래그의 소스나 대상 둘 다 될 수 있습니다.

설명

유저 아이템은 업데이트될 때마다 DG_MSG_UPDATE 메시지를 수신합니다. 만약 유저 아이템의 업데이트 프로세스에 시간이 너무 많이 걸리면, 해당 항목에 대한 부분 업데이트를 활성화하는 것이 좋습니다. 만약 부분 업데이트가 활성화되면, 일반 업데이트 메시지 외에도 DG는 부분 업데이트 메시지도 자동으로 보내거나 다음 경우에 애플리케이션의 요구사항에 대해 보냅니다:

• 만약 애플리케이션이 다이얼로그를 열고, 표시하고, 최대화하고, 복원하면 모든 다이얼로그 항목들은 다이얼로그 항목 순서대로 업데이트됩니다. 다시 그리기에 오랜 시간이 걸리고 부분 업데이트가 활성화된 유저 아이템이 있는 경우, 부분 업데이트 메시지는 다시 그리기를 시도할 때 전송됩니다. 일반 업데이트 메시지는 다른 모든 다이얼로그 항목들이 업데이트된 후에만 나중에 전송됩니다. 이러한 방식으로 이러한 동작을 하는 동안, (항목 순서상 뒤에 있는) 유저 아이템을 업데이트 하고 있을 때 다이얼로그 항목들이 보이지 않는 상태로 있는 것을 방지합니다.
• Windows에서 만약 전체 드래그 모드가 시스템에서 켜지고 부분 업데이트가 활성화되면, DG는 사용자가 유저 아이템의 부모 다이얼로그를 이동하거나 리사이즈하는 동안 부분 업데이트 메시지를 전송하고, 사용자가 다이얼로그 이동 또는 리사이즈를 마치는 즉시 하나의 일반 업데이트 메시지를 보냅니다. 만약 부분 업데이트가 비활성화되면, 부분 업데이트 메시지 대신 일반 업데이트 메시지가 전송되고 유저 아이템은 마우스가 이동할 때마다 완전히 다시 칠해지므로 다이얼로그를 리사이즈할 때 요동칩니다.
• 애플리케이션은 DGDisableNormalUpdate 함수를 사용하여 다이얼로그에서 일반 업데이트 메커니즘을 비활성화했습니다. 이 경우 부분 업데이트가 활성화된 다이얼로그의 모든 유저 아이템들은 부분 업데이트 메시지만 수신합니다. 만약 DGEnableNormalUpdate로 일반 업데이트 메커니즘이 복원되면, 일반 업데이트 메시지가 유저 아이템으로 전송됩니다. 다음은 다이얼로그에 대한 일반 업데이트를 비활성화하는 유용한 예제입니다: 애플리케이션이 동시에 많은 Modeless 창들을 열었고, 각 창은 계산하고 다시 그리는 데 오랜 시간이 걸리는 그래픽을 가진 유저 아이템을 가지고 있으며, 이러한 창들은 화면에 배치되어야 한다고 가정합니다. (예를 들면, 타일 또는 캐스케이드) 만약 부분 업데이트가 활성화되지 않으면 창들은 다음과 같은 방식으로 배열됩니다: 첫 번째 창은 새로운 위치로 이동되고, 리사이즈되고, 전체 콘텐츠가 다시 그려집니다. 다시 그리기 프로세스가 지속될 때까지 다음 창의 크기와 위치는 변경되지 않습니다. 두 개의 창을 배열하는 사이에는 오랜 시간이 걸립니다. 만약 부분 업데이트가 활성화되면, 첫 번째 창은 이동되고, 리사이즈되고, 부분 업데이트 메시지를 수신합니다. 이 메시지에 응답하면 배경을 다시 칠하고 시간 소모없이 일부 기본 드로잉 함수들을 수행할 수 있습니다. 다음 창에서 이 프로세스가 계속됩니다. 모든 창들의 새 위치와 크기가 설정된 후, DG는 각 창에 대한 일반 업데이트 메시지들을 보냅니다. 이 경우, 첫 번째 일반 업데이트 메시지가 전송된 후에는 창 배열이 발생하지 않습니다.

다이얼로그 콜백 함수가 DG_MSG_UPDATE 메시지를 수신할 때, msgData 파라미터는 애플리케이션이 유저 아이템을 업데이트하는 데 필요한 모든 정보를 포함하는 DGUserUpdateData structure에 대한 포인터입니다. 메시지 타입은 DG_UUT_NORMAL, DG_UUT_PARTIAL, DG_UUT_INUPDATE 값 중 하나가 될 수 있습니다. 만약 유저 아이템을 완전히 다시 칠해야 하는 경우, DG는 DG_UUT_NORMAL 타입으로 업데이트 메시지를 보냅니다. 만약 유저 아이템을 부분적으로 업데이트해야 하고 부분 업데이트가 활성화되면 DG_UUT_PARTIAL 타입 업데이트 메시지가 전송됩니다. 일반적으로 애플리케이션은 배경을 지우거나 프레임을 그리거나 부분 업데이트 메시지를 수신할 때 일부 기본 그리기를 수행합니다. DG_UUT_INUPDATE 타입 메시지는 특별한 경우에 전송됩니다: 만약 업데이트 함수가 오래 걸리고 컨트롤이 이벤트 루프로 실행되도록 놔두면, 업데이트 프로세스 중에 다른 업데이트 이벤트가 생성됩니다. (예를 들면 작업 전환 때문에) 이 경우, 애플리케이션은 중단된 업데이트 프로세스의 업데이트 영역으로부터 새로운 무효 영역을 클리핑할 수 있습니다.

업데이트 메시지들을 보내기 전에 DG는 기본 배경색을 가진 유저 아이템의 무효화된 부분을 지웁니다. 이 색상은 DGUserSetBackgroundColor와 DGUserGetBackgroundColor 함수로 각각 설정하고 가져올 수 있습니다.

모든 업데이트 메시지에 의해 현재 무효 영역이 메시지 데이터로 전송됩니다. 만약 유저 아이템에 대해 부분 업데이트가 활성화되면, 부분 업데이트 메시지와 함께 전송된 영역은 DG에 의해 수집되고, 부분 업데이트가 종료되면 그것들의 조합은 일반 업데이트 메시지와 함께 전송됩니다. 업데이트 영역 핸들은 DGUserUpdateData structure의 updateRgn 멤버에 리턴됩니다. 그것은 Windows에서 HRGN으로, Macintosh에서는 항상 NULL로 캐스팅되어야 합니다.

애플리케이션은 유저 아이템들에 시스템 종속 드로잉 함수들을 사용할 수 있습니다. 만약 DGUserUpdateData structure이면, 그리기 컨텍스트가 drawContext 멤버에 전송됩니다. 이 멤버는 Windows의 HDC와 Macintosh의 CGContextRef로 캐스팅되어야 합니다. 그리기 컨텍스트의 원점을 유저 아이템의 왼쪽 상단 모서리로 설정합니다.

유저 아이템에 대한 부분 업데이트는 GRC 스크립트에서 활성화할 수 있습니다. 기본 유저 아이템 업데이트 메커니즘을 제어하려면 DGEnableNormalUpdate와 DGDisableNormalUpdate 함수를 사용합니다.

만약 유저 아이템을 즉시 다시 그려야 한다면 DGUserRedrawItem 함수를 displayImmediately = true 파라미터와 함께 사용합니다. 그렇지 않으면 DGUserRedrawItem 함수를 displayImmediately = false 파라미터와 함께 사용할 수 있습니다.

만약 유저 아이템에 프레임이 있는 경우, 프레임은 업데이트 영역에서 잘려나갑니다. DGUserGetClientRect 함수를 사용하여 애플리케이션이 그릴 수 있는 직사각형을 가져옵니다. 만약 유저 아이템에 프레임이 없는 경우 DGUserGetClientRect와 DGGetItemRect는 동일한 값들을 가져옵니다.

유저 아이템은 커서가 그것들 위로 이동할 때 DG_MSG_MOUSEMOVE 메시지를 수신할 수 있습니다. 기본적으로 DG는 DG_MSG_MOUSEMOVE 메시지를 유저 아이템으로 전송하지 않습니다. 만약 애플리케이션이 이 메시지를 필요로 하는 경우, 유저 아이템에 대해 DG_MSG_MOUSEMOVE를 3번째 파라미터로 한 DGEnableMessage를 호출해야 합니다. 커서를 커스텀 형태로 변경하려면, DG는 유저 아이템 위에서 기본 커서로 설정하지 못하도록 DG_MSG_MOUSEMOVE 메시지를 처리할 때 그것이 리턴되어야 합니다. 만약 0이 리턴되면 DG는 기본 화살표 커서를 설정합니다.

요구사항

버전: DG 2.2.0 또는 이후

헤더: DG.h

참고사항

다이얼로그 항목 타입, 아이콘, 그림, 정적 텍스트, 유저 컨트롤
DGUserRedrawItem, DGEnableNormalUpdate, DGDisableNormalUpdate, DGEnableMessage
DGUserUpdateData, DGUserMsgData
콜백 함수, DG_MSG_CLICK, DG_MSG_DOUBLECLICK, DG_MSG_MOUSEMOVE, DG_MSG_UPDATE